Merge pull request realpython#393 from Zearin/code-blocks

Code blocks

Author: sigmavirus24

Readme.rst

@@ -16,17 +16,18 @@ basis.
 
 Topics include:
 
-- Platform/version specific installations
+- Platform- and version-specific installations
 - Py2app, Py2exe, bbfreeze, pyInstaller
-- Pip / virtualenv
-- Documentation. Writing it.
-- server configurations / tools for various web frameworks
+- Pip
+- Virtualenv
 - fabric
-- exhaustive module recommendations, grouped by topic/purpose
-- Testing. Jenkins + tox guides.
-- How to interface w/ hg from git easily
-- what libraries to use for what
-
-If you are not fond of reading reStructuredText, there is an
+- Exhaustive module recommendations, grouped by topic/purpose
+- Which libraries to use for what
+- Server configurations & tools for various web frameworks
+- Documentation: writing it
+- Testing: Jenkins & tox guides
+- How to easily interface ``hg`` from ``git`` easily
+
+If you aren't fond of reading reStructuredText, there is an
 almost up-to-date `HTML version at docs.python-guide.org
 <http://docs.python-guide.org>`_.

docs/dev/env.rst

@@ -16,7 +16,7 @@ Vim is a text editor which uses keyboard shortcuts for editing instead of menus
 or icons. There exist a couple of plugins and settings for the VIM editor to
 aid Python development. If you only develop in Python, a good start is to set
 the default settings for indentation and line-wrapping to values compliant with
-:pep:`8`. In your home directory, open a file called `.vimrc` and add the
+:pep:`8`. In your home directory, open a file called ``.vimrc`` and add the
 following lines::
 
     set textwidth=79  " lines longer than 79 columns will be broken
@@ -42,11 +42,11 @@ If your VIM is compiled with `+python` you can also utilize some very handy
 plugins to do these checks from within the editor.
 
 For PEP8 checking, install the vim-pep8_ plugin, and for pyflakes you can
-install vim-pyflakes_. Now you can map the functions `Pep8()` or `Pyflakes()`
+install vim-pyflakes_. Now you can map the functions ``Pep8()`` or ``Pyflakes()``
 to any hotkey or action you want in Vim. Both plugins will display errors at
 the bottom of the screen, and provide an easy way to jump to the corresponding
 line. It's very handy to call these functions whenever you save a file. In
-order to do this, add the following lines to your `vimrc`::
+order to do this, add the following lines to your ``.vimrc``::
 
     autocmd BufWritePost *.py call Pyflakes()
     autocmd BufWritePost *.py call Pep8()
@@ -67,12 +67,12 @@ Python-mode
 Python-mode_ is a complex solution in VIM for working with Python code.
 It has:
 
-- Asynchronous Python code checking (pylint, pyflakes, pep8, mccabe) in any combination
+- Asynchronous Python code checking (``pylint``, ``pyflakes``, ``pep8``, ``mccabe``) in any combination
 - Code refactoring and autocompletion with Rope
 - Fast Python folding
 - Virtualenv support
 - Search by Python documentation and run Python code
-- Auto PEP8 error fixes
+- Auto PEP8_ error fixes
 
 And more.
 
@@ -105,10 +105,10 @@ already an Emacs user is `Python Programming in Emacs`_ at EmacsWiki.
 TextMate
 --------
 
-"`TextMate <http://macromates.com/>`_ brings Apple's approach to operating
-systems into the world of text editors. By bridging UNIX underpinnings and GUI,
-TextMate cherry-picks the best of both worlds to the benefit of expert
-scripters and novice users alike."
+    `TextMate <http://macromates.com/>`_ brings Apple's approach to operating
+    systems into the world of text editors. By bridging UNIX underpinnings and GUI,
+    TextMate cherry-picks the best of both worlds to the benefit of expert
+    scripters and novice users alike.
 
 Sublime Text
 ------------
@@ -143,7 +143,7 @@ The most popular Eclipse plugin for Python development is Aptana's
 Komodo IDE
 ----------
 `Komodo IDE <http://www.activestate.com/komodo-ide>`_ is developed by
-ActiveState and is a commercial IDE for Windows, Mac and Linux.
+ActiveState and is a commercial IDE for Windows, Mac, and Linux.
 
 
 Spyder
@@ -189,18 +189,22 @@ virtualenv
 Virtualenv is a tool to keep the dependencies required by different projects
 in separate places, by creating virtual Python environments for them.
 It solves the "Project X depends on version 1.x but, Project Y needs 4.x"
-dilemma and keeps your global site-packages directory clean and manageable.
+dilemma, and keeps your global site-packages directory clean and manageable.
 
 `virtualenv <http://www.virtualenv.org/en/latest/index.html>`_ creates
 a folder which contains all the necessary executables to contain the
 packages that a Python project would need. An example workflow is given.
 
-Install virtualenv::
+Install virtualenv:
+
+.. code-block:: console
 
     $ pip install virtualenv
 
 
-Create a virtual environment for a project::
+Create a virtual environment for a project:
+
+.. code-block:: console
 
     $ cd my_project
     $ virtualenv venv
@@ -211,22 +215,28 @@ library which you can use to install other packages. The name of the
 virtual environment (in this case, it was ``venv``) can be anything;
 omitting the name will place the files in the current directory instead.
 
-To start using the virtual environment, run::
+To start using the virtual environment, run:
+
+.. code-block:: console
 
     $ source venv/bin/activate
 
 
 The name of the current virtual environment will now appear on the left
 of the prompt (e.g. ``(venv)Your-Computer:your_project UserName$``) to
 let you know that it's active. From now on, any package that you install
-using ``pip`` will be placed in the venv folder, isolated from the global
-Python installation. Install packages as usual::
+using ``pip`` will be placed in the ``venv`` folder, isolated from the global
+Python installation. 
+
+Install packages as usual:
+
+.. code-block:: console
 
     $ pip install requests
 
-To stop using an environment simply type ``deactivate``. To remove the
+To stop using an environment, simply type ``deactivate``. To remove the
 environment, just remove the directory it was installed into. (In this
-case, it would be ``rm -rf venv``).
+case, it would be ``rm -rf venv``.)
 
 Other Notes
 ^^^^^^^^^^^
@@ -239,7 +249,7 @@ for keeping the package list clean in case it needs to be accessed later.
 In order to keep your environment consistent, it's a good idea to "freeze"
 the current state of the environment packages. To do this, run
 
-::
+.. code-block:: console
 
     $ pip freeze > requirements.txt
 
@@ -249,7 +259,7 @@ versions. Later, when a different developer (or you, if you need to re-
 create the environment) can install the same packages, with the same
 versions by running
 
-::
+.. code-block:: console
 
     $ pip install -r requirements.txt
 
@@ -265,14 +275,14 @@ virtualenvwrapper
 `Virtualenvwrapper <http://pypi.python.org/pypi/virtualenvwrapper>`_ makes
 virtualenv a pleasure to use by wrapping the command line API with a nicer CLI.
 
-::
+.. code-block:: console
 
     $ pip install virtualenvwrapper
 
 
-Put this into your `~/.bash_profile` (Linux/Mac) file:
+Put this into your ``~/.bash_profile`` (Linux/Mac) file:
 
-::
+.. code-block:: console
 
     $ export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages'
 
@@ -312,7 +322,7 @@ most out of using Python interactively. Its main components are:
 * Flexible, embeddable interpreters to load into your own projects.
 * Tools for high level and interactive parallel computing.
 
-::
+.. code-block:: console
 
     $ pip install ipython
 
@@ -333,7 +343,7 @@ Python interpreter for Unix-like operating systems. It has the following feature
 * Auto-indentation.
 * Python 3 support.
 
-::
+.. code-block:: console
 
     $ pip install bpython
 

docs/index.rst

@@ -8,7 +8,8 @@ The Hitchhiker's Guide to Python!
 
 Welcome to The Hitchhiker's Guide to Python.
 
-**This guide is currently under heavy active development.**  If you'd like to help, `fork us on GitHub <https://github.com/kennethreitz/python-guide>`_!
+**This guide is currently under heavy active development.**  If you'd like to help, 
+`fork us on GitHub <https://github.com/kennethreitz/python-guide>`_!
 
 This *opinionated* guide exists to provide both novice and expert Python
 developers a best-practice handbook to the installation, configuration, and

docs/intro/duction.rst

@@ -7,14 +7,14 @@ Python is a general-purpose, high-level programming language similar
 to Tcl, Perl, Ruby, Scheme, or Java. Some of its main key features
 include:
 
-* very clear, readable syntax
+* **very clear, readable syntax**
 
   Python's philosophy focuses on readability, from code blocks
   delineated with significant whitespace to intuitive keywords in
   place of inscrutable punctuation
 
-* extensive standard libraries and third party modules for virtually
-  any task
+* **extensive standard libraries and third party modules for virtually
+  any task**
 
   Python is sometimes described with the words "batteries included"
   for its extensive
@@ -30,21 +30,21 @@ include:
   the `Django <http://www.djangoproject.com>`_ web framework and the
   `NumPy <http://numpy.scipy.org>`_ set of math routines.
 
-* integration with other systems
+* **integration with other systems**
 
   Python can integrate with `Java libraries <http://www.jython.org>`_,
   enabling it to be used with the rich Java environment that corporate
   programmers are used to. It can also be
   `extended by C or C++ modules <http://docs.python.org/extending/>`_
   when speed is of the essence.
 
-* ubiquity on computers
+* **ubiquity on computers**
 
   Python is available on Windows, \*nix, and Mac. It runs wherever the
   Java virtual machine runs, and the reference implementation CPython
   can help bring Python to wherever there is a working C compiler.
 
-* friendly community
+* **friendly community**
 
   Python has a vibrant and large :ref:`community <the-community>`
   which maintains wikis, conferences, countless repositories,
@@ -77,10 +77,12 @@ For the Community
 
 All contributions to the Guide are welcome, from Pythonistas of all levels.
 If you think there's a gap in what the Guide covers, fork the Guide on
-GitHub and submit a pull request. Contributions are welcome from everyone,
-whether they're an old hand or a first-time Pythonista, and the authors to
-the Guide will gladly help if you have any questions about the
-appropriateness, completeness, or accuracy of a contribution.
+GitHub and submit a pull request. 
+
+Contributions are welcome from everyone, whether they're an old hand or a 
+first-time Pythonista, and the authors to the Guide will gladly help if you 
+have any questions about the appropriateness, completeness, or accuracy of 
+a contribution.
 
 To get started working on The Hitchhiker's Guide, see the :doc:`/notes/contribute` page.
 

docs/notes/styleguide.rst

@@ -30,8 +30,8 @@ Strive to keep any contributions relevant to the :ref:`purpose of The Guide
 * `Cite <http://sphinx.pocoo.org/rest.html?highlight=citations#citations>`_
   references where needed.
 * If a subject isn't directly relevant to Python, but useful in conjunction
-  with Python (ex: Git, Github, Databases), reference by linking to useful
-  resources and describe why it's useful to Python.
+  with Python (e.g., Git, GitHub, Databases), reference by linking to useful
+  resources, and describe why it's useful to Python.
 * When in doubt, ask.
 
 Headings

docs/scenarios/admin.rst

@@ -21,7 +21,7 @@ latter will ssh into each server, cd to our project directory, activate the
 virtual environment, pull the newest codebase, and restart the application
 server.
 
-::
+.. code-block:: python
 
     from fabric.api import cd, env, prefix, run, task
 

docs/scenarios/db.rst

@@ -20,9 +20,9 @@ SQLAlchemy
 Unlike many database libraries it not only provides an ORM layer but also a
 generalized API for writing database-agnostic code without SQL.
 
-::
+.. code-block:: console
 
-    pip install sqlalchemy
+    $ pip install sqlalchemy
 
 Django ORM
 ----------

docs/scenarios/imaging.rst

@@ -23,6 +23,6 @@ the instructions for your platform `here <https://pypi.python.org/pypi/Pillow/2.
 
 After that, it's straightforward:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ pip install Pillow

docs/scenarios/scrape.rst

@@ -56,7 +56,7 @@ After a quick analysis, we see that in our page the data is contained in
 two elements - one is a div with title 'buyer-name' and the other is a
 span with class 'item-price':
 
-::
+.. code-block:: html
 
     <div title="buyer-name">Carson Busses</div>
     <span class="item-price">$29.95</span>

docs/scenarios/speed.rst

@@ -8,9 +8,9 @@ Using a slightly modified version of `David Beazleys`_ CPU bound test code
 (added loop for multiple tests), you can see the difference between CPython
 and PyPy's processing.
 
-::
+.. code-block:: console
 
-   PyPy
+   # PyPy
    $ ./pypy -V
    Python 2.7.1 (7773f8fc4223, Nov 18 2011, 18:47:10)
    [PyPy 1.7.0 with GCC 4.4.3]
@@ -21,9 +21,9 @@ and PyPy's processing.
    0.0440690517426
    0.0695300102234
 
-::
+.. code-block:: console
 
-   CPython
+   # CPython
    $ ./python -V
    Python 2.7.1
    $ ./python measure2.py
@@ -72,9 +72,10 @@ Cython
 with which you are able to write C and C++ modules for Python. Cython also 
 allows you to call functions from compiled C libraries. Using Cython allows 
 you to take advantage of Python's strong typing of variables and operations.  
-Here is an example of strong typing with Cython:
 
-.. code-block:: python
+Here's an example of strong typing with Cython:
+
+.. code-block:: cython
 
     def primes(int kmax):
     """Calculation of prime numbers with additional
@@ -128,7 +129,7 @@ Notice that in the Cython version you declare integers and integer arrays for
 to be compiled into C types while also creating a Python list:
 
 
-.. code-block:: python
+.. code-block:: cython
 
     def primes(int kmax):
         """Calculation of prime numbers with additional
@@ -190,18 +191,22 @@ The `pyximport` module allows you to import `pyx` files (e.g., `primesCy.pyx`) w
 The `pyximport.install()` command allows the Python interpreter to start the Cython compiler directly to generate C-code,
 which is automatically compiled to a `*.so` C-library. Cython is able to import this library for you in your Python-code.
 Very easy and very efficient. With the `time.time()` function you are able to compare the time between this 2 different calls to find 500 prime numbers.
+On a standard notebook (dual core AMD E-450 1.6 GHz), the measured values are:
+
+.. code-block:: console
+
+    Cython time: 0.0054 seconds
 
-On a standard notebook (dualcore AMD E-450 1,6 GHz)  the measured values are:
+    Python time: 0.0566 seconds
 
-Cython time: 0.0054 seconds
 
-Python time: 0.0566 seconds
 
 And here the output of an embedded `ARM beaglebone <http://beagleboard.org/Products/BeagleBone>`_  machine:
+.. code-block:: console
 
-Cython time: 0.0196 seconds
+    Cython time: 0.0196 seconds
 
-Python time: 0.3302 seconds
+    Python time: 0.3302 seconds
 
 Pyrex
 -----