Merge pull request #297 from kuyan/master

Formatting, code highlighting fixes.

docs/dev/env.rst

@@ -16,8 +16,8 @@ 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 <http://www.python.org/dev/peps/pep-0008/>`_. In your home directory,
+:pep:`8`. In your home directory, open a file called `.vimrc` and add the
-open a file called `.vimrc` and add the following lines:::
+following lines:::
 
     set textwidth=79  " lines longer than 79 columns will be broken
     set shiftwidth=4  " operation >> indents 4 columns; << unindents 4 columns
@@ -113,12 +113,14 @@ scripters and novice users alike."
 Sublime Text
 ------------
 
-"`Sublime Text <http://www.sublimetext.com/>`_ is a sophisticated text editor
+    `Sublime Text <http://www.sublimetext.com/>`_ is a sophisticated text
-for code, html and prose. You'll love the slick user interface and
+    editor for code, markup and prose. You'll love the slick user interface,
-extraordinary features."
+    extraordinary features and amazing performance.
 
 Sublime Text has excellent support for editing Python code and uses Python for
-its plugin API.
+its plugin API. It also has plugins a diverse variety of plugins, `some of which <https://github.com/SublimeLinter/SublimeLinter>`_
+allow for in-editor PEP8 checking and code "linting".
+
 
 IDEs
 ::::

docs/intro/community.rst

@@ -27,7 +27,7 @@ PEPs
 PEPs are *Python Enhancement Proposals*. They describe changes to Python itself,
 or the standards around it.
 
-There are three different types of PEPs (as defined by `PEP1 <http://www.python.org/dev/peps/pep-0001/>`_):
+There are three different types of PEPs (as defined by :pep:`1`):
 
     **Standards**
         Describes a new feature or implementation.
@@ -45,13 +45,13 @@ Notable PEPs
 
 There are a few PEPs that could be considered required reading:
 
-- `PEP8 <http://www.python.org/dev/peps/pep-0008/>`_: The Python Style Guide.
+- :pep:`8`: The Python Style Guide.
     Read this. All of it. Follow it.
 
-- `PEP20 <http://www.python.org/dev/peps/pep-0020/>`_: The Zen of Python.
+- :pep:`20`: The Zen of Python.
     A list of 19 statements that briefly explain the philosophy behind Python.
 
-- `PEP257 <http://www.python.org/dev/peps/pep-0257/>`_: Docstring Conventions.
+- :pep:`257`: Docstring Conventions.
     Gives guidelines for semantics and conventions associated with Python
     docstrings.
 

docs/intro/duction.rst

@@ -82,7 +82,6 @@ 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
+To get started working on The Hitchhiker's Guide, see the :doc:`/notes/contribute` page.
-the: doc:`/notes/contribute` page.
 
 

docs/intro/learning.rst

@@ -105,7 +105,7 @@ is focused on the more advanced crowd.
 
 It starts with topics like decorators (with caching, proxy, and context manager
 case-studies), method resolution order, using super() and meta-programming, and
-general PEP8 best practices.
+general :pep:`8` best practices.
 
 It has a detailed, multi-chapter case study on writing and releasing a package
 and eventually an application, including a chapter on using zc.buildout.  Later

docs/notes/license.rst

@@ -1,4 +1,5 @@
+=======
 License
--------
+=======
 
-.. todo:: Determine License
+The Guide is licensed under the `Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported license <https://creativecommons.org/licenses/by-nc-sa/3.0/>`_.

docs/notes/styleguide.rst

@@ -39,24 +39,32 @@ Headings
 
 Use the following styles for headings.
 
-Chapter title::
+Chapter title:
+
+.. code-block:: rest
 
     #########
     Chapter 1
     #########
 
-Page title::
+Page title:
+
+.. code-block:: rest
 
     ===================
     Time is an Illusion
     ===================
 
-Section headings::
+Section headings:
+
+.. code-block:: rest
 
     Lunchtime Doubly So
     -------------------
 
-Sub section headings::
+Sub section headings:
+
+.. code-block:: rest
 
     Very Deep
     ~~~~~~~~~
@@ -74,7 +82,9 @@ Code Examples
 
 Wrap all code examples at 70 characters to avoid horizontal scrollbars.
 
-Command line examples::
+Command line examples:
+
+.. code-block:: rest
 
     .. code-block:: console
 
@@ -83,7 +93,9 @@ Command line examples::
 
 Be sure to include the ``$`` prefix before each line.
 
-Python interpreter examples::
+Python interpreter examples:
+
+.. code-block:: rest
 
     Label the example::
 
@@ -91,7 +103,9 @@ Python interpreter examples::
 
         >>> import this
 
-Python examples::
+Python examples:
+
+.. code-block:: rest
 
     Descriptive title::
 
@@ -103,16 +117,20 @@ Python examples::
 Externally Linking
 ------------------
 
-* Prefer labels for well known subjects (ex: proper nouns) when linking::
+* Prefer labels for well known subjects (ex: proper nouns) when linking:
 
-    Sphinx_ is used to document Python.
+  .. code-block:: rest
 
-    .. _Sphinx: http://sphinx.pocoo.org
+      Sphinx_ is used to document Python.
+
+      .. _Sphinx: http://sphinx.pocoo.org
 
 * Prefer to use descriptive labels with inline links instead of leaving bare
-  links::
+  links:
 
-    Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_
+  .. code-block:: rest
+
+      Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_
 
 * Avoid using labels such as "click here", "this", etc. preferring
   descriptive labels (SEO worthy) instead.
@@ -124,7 +142,9 @@ To cross-reference other parts of this documentation, use the `:ref:
 <http://sphinx.pocoo.org/markup/inline.html#cross-referencing-arbitrary-locations>`_
 keyword and labels.
 
-To make reference labels more clear and unique, always add a ``-ref`` suffix::
+To make reference labels more clear and unique, always add a ``-ref`` suffix:
+
+.. code-block:: rest
 
     .. _some-section-ref:
 
@@ -137,14 +157,18 @@ Notes and Warnings
 Make use of the appropriate `admonitions directives
 <http://sphinx.pocoo.org/rest.html#directives>`_ when making notes.
 
-Notes::
+Notes:
+
+.. code-block:: rest
 
     .. note::
         The Hitchhiker’s Guide to the Galaxy has a few things to say
         on the subject of towels. A towel, it says, is about the most
         massively useful thing an interstellar hitch hiker can have.
 
-Warnings::
+Warnings:
+
+.. code-block:: rest
 
     .. warning:: DON'T PANIC
 
@@ -156,7 +180,7 @@ Please mark any incomplete areas of The Guide with a `todo directive
 avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub
 documents or large incomplete sections.
 
-::
+.. code-block:: rest
 
     .. todo::
         Learn the Ultimate Answer to the Ultimate Question

docs/scenarios/db.rst

@@ -5,7 +5,7 @@ DB-API
 ------
 
 The Python Database API (DB-API) defines a standard interface for Python
-database access modules. It's documented in `PEP 249 <http://www.python.org/dev/peps/pep-0249/>`_.
+database access modules. It's documented in :pep:`249`.
 Nearly all Python database modules such as `sqlite3`, `psycopg` and
 `mysql-python` conform to this interface.
 

docs/scenarios/imaging.rst

@@ -12,7 +12,7 @@ The `Python Imaging Library <http://www.pythonware.com/products/pil/>`_, or PIL
 for short, is *the* library for image manipulation in Python. Unfortunately, its
 development has stagnated, with its last release in 2009.
 
-Lucky for you, there's an actively-developed fork of PIL called `Pillow <http://python-imaging.github.io/>`_ -
+Luckily for you, there's an actively-developed fork of PIL called `Pillow <http://python-imaging.github.io/>`_ -
 it's easier to install, runs on all operating systems, and supports Python 3.
 
 Installation

docs/scenarios/web.rst

@@ -18,7 +18,7 @@ interface between web servers and Python web application frameworks. By
 standardizing behavior and communication between web servers and Python web
 frameworks, WSGI makes it possible to write portable Python web code that
 can be deployed in any :ref:`WSGI-compliant web server <wsgi-servers-ref>`.
-WSGI is documented in `PEP-3333 <http://www.python.org/dev/peps/pep-3333/>`_.
+WSGI is documented in :pep:`3333`.
 
 
 Frameworks

docs/writing/documentation.rst

@@ -104,9 +104,7 @@ In Python, *docstrings* describe modules, classes, and functions: ::
         """Returns the square root of self times self."""
         ...
 
-In general, follow the `comment section of PEP 0008`_ (the "Python Style Guide").
+In general, follow the comment section of :pep:`8#comments` (the "Python Style Guide").
-
-.. _comment section of PEP 0008: http://www.python.org/dev/peps/pep-0008/#comments
 
 Commenting Sections of Code
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -137,9 +135,7 @@ operation of the function or class: ::
         """Returns the square root of self times self."""
 	...
 
-.. seealso:: Further reading on docstrings: `PEP 0257`_
+.. seealso:: Further reading on docstrings: :pep:`257`
-
-.. _PEP 0257: http://www.python.org/dev/peps/pep-0257/
 
 
 Other Tools

docs/writing/structure.rst

@@ -35,9 +35,9 @@ include:
 
 - Multiple and messy circular dependencies: if your classes
   Table and Chair in furn.py need to import Carpenter from workers.py
-  to answer a question such as table.isdoneby(),
+  to answer a question such as ``table.isdoneby()``,
   and if conversely the class Carpenter needs to import Table and Chair,
-  to answer the question carpenter.whatdo(), then you
+  to answer the question ``carpenter.whatdo()``, then you
   have a circular dependency. In this case you will have to resort to
   fragile hacks such as using import statements inside
   methods or functions.
@@ -236,7 +236,7 @@ processes are spawned to respond to external requests that can
 happen at the same time. In this case, holding some state into instantiated
 objects, which means keeping some static information about the world, is prone
 to concurrency problems or race-conditions. Sometimes, between the initialization of
-the state of an object (usually done with the __init__() method) and the actual use
+the state of an object (usually done with the ``__init__()`` method) and the actual use
 of the object state through one of its methods, the world may have changed, and
 the retained state may be outdated. For example, a request may load an item in
 memory and mark it as read by a user. If another request requires the deletion
@@ -383,7 +383,7 @@ Python has two kinds of built-in or user-defined types.
 
 Mutable types are those that allow in-place modification
 of the content. Typical mutables are lists and dictionaries:
-All lists have mutating methods, like append() or pop(), and
+All lists have mutating methods, like ``append()`` or ``pop()``, and
 can be modified in place. The same goes for dictionaries.
 
 Immutable types provide no method for changing their content.
@@ -418,7 +418,7 @@ its parts, it is much more efficient to accumulate the parts in a list,
 which is mutable, and then glue ('join') the parts together when the
 full string is needed. One thing to notice, however, is that list
 comprehensions are better and faster than constructing a list in a loop
-with calls to append().
+with calls to ``append()``.
 
 **Bad**
 
@@ -448,10 +448,10 @@ with calls to append().
     nums = [str(n) for n in range(20)]
     print "".join(nums)
 
-One final thing to mention about strings is that using join() is not always
+One final thing to mention about strings is that using ``join()`` is not always
 best. In the instances where you are creating a new string from a pre-determined
 number of strings, using the addition operator is actually faster, but in cases
-like above or in cases where you are adding to an existing string, using join()
+like above or in cases where you are adding to an existing string, using ``join()``
 should be your preferred method.
 
 .. code-block:: python
@@ -464,11 +464,10 @@ should be your preferred method.
     foo = ''.join([foo, 'ooo'])
 
 .. note::
-    You can also use the **%** formatting operator to concatenate the
+    You can also use the ``%`` formatting operator to concatenate the
-    pre-determined number of strings besides **join()** and **+**. However,
+    pre-determined number of strings besides ``join()`` and ``+``. However,
-    according to `PEP 3101 <http://www.python.org/dev/peps/pep-3101/>`_,
+    according to :pep:`3101`, the ``%`` operator became deprecated in
-    **%** operator became deprecated in Python 3.1 and will be replaced by the
+    Python 3.1 and will be replaced by the ``format()`` method in the later versions.
-    **format()** method in the later versions.
 
 .. code-block:: python
 

docs/writing/style.rst

@@ -362,7 +362,7 @@ For more information see this `StackOverflow <http://stackoverflow.com/questions
 Zen of Python
 -------------
 
-Also known as PEP 20, the guiding principles for Python's design.
+Also known as :pep:`20`, the guiding principles for Python's design.
 
 ::
 
@@ -397,9 +397,7 @@ slides from a Python user group
 PEP 8
 -----
 
-PEP 8 is the de-facto code style guide for Python.
+:pep:`8` is the de-facto code style guide for Python.
-
-    `PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_
 
 Conforming your Python code to PEP 8 is generally a good idea and helps make
 code more consistent when working on projects with other developers. There

docs/writing/tests.rst

@@ -16,7 +16,7 @@ Some general rules of testing:
   alone, and also within the test suite, regardless of the order they are called.
   The implication of this rule is that each test must be loaded with a fresh
   dataset and may have to do some cleanup afterwards. This is usually
-  handled by setUp() and tearDown() methods.
+  handled by `setUp()` and `tearDown()` methods.
 
 - Try hard to make tests that run fast. If one single test needs more than a
   few millisecond to run, development will be slowed down or the tests will not
@@ -112,7 +112,7 @@ test suite runs.
 
 A simple doctest in a function:
 
-::
+.. code-block:: python
 
     def square(x):
         """Squares x.
@@ -142,7 +142,7 @@ py.test
 
 py.test is a no-boilerplate alternative to Python's standard unittest module.
 
-::
+.. code-block:: console
 
     $ pip install pytest
 
@@ -150,7 +150,7 @@ Despite being a fully-featured and extensible test tool, it boasts a simple
 syntax. Creating a test suite is as easy as writing a module with a couple of
 functions
 
-::
+.. code-block:: console
 
     # content of test_sample.py
     def func(x):
@@ -161,7 +161,7 @@ functions
 
 and then running the `py.test` command
 
-::
+.. code-block:: console
 
     $ py.test
     =========================== test session starts ============================
@@ -193,7 +193,7 @@ Nose
 nose extends unittest to make testing easier.
 
 
-::
+.. code-block:: console
 
     $ pip install nose
 
@@ -210,7 +210,7 @@ tox
 tox is a tool for automating test environment management and testing against
 multiple interpreter configurations
 
-::
+.. code-block:: console
 
     $ pip install tox
 
@@ -227,14 +227,14 @@ API and better assertions over the one available in previous versions of Python.
 
 If you're using Python 2.6 or below, you can install it with pip
 
-::
+.. code-block:: console
 
     $ pip install unittest2
 
 You may want to import the module under the name unittest to make porting code
 to newer versions of the module easier in the future
 
-::
+.. code-block:: python
 
     import unittest2 as unittest
 
@@ -253,7 +253,7 @@ mock
 
 mock is a library for testing in Python.
 
-::
+.. code-block:: console
 
     $ pip install mock
 
@@ -262,7 +262,7 @@ make assertions about how they have been used.
 
 For example, you can monkey patch a method
 
-::
+.. code-block:: console
 
     from mock import MagicMock
     thing = ProductionClass()
@@ -275,7 +275,7 @@ To mock classes or objects in a module under test, use the ``patch`` decorator.
 In the example below, an external search system is replaced with a mock that
 always returns the same result (but only for the duration of the test).
 
-::
+.. code-block:: console
 
     def mock_search(self):
         class MockSearchQuerySet(SearchQuerySet):