Use the :pep: tag instead of directly linking PEPs

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").
-
-.. _comment section of PEP 0008: http://www.python.org/dev/peps/pep-0008/#comments
+In general, follow the comment section of :pep:`8#comments` (the "Python Style Guide").
 
 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`_
-
-.. _PEP 0257: http://www.python.org/dev/peps/pep-0257/
+.. seealso:: Further reading on docstrings: :pep:`257`
 
 
 Other Tools

docs/writing/structure.rst

@@ -466,9 +466,8 @@ should be your preferred method.
 .. note::
     You can also use the **%** formatting operator to concatenate the
     pre-determined number of strings besides **join()** and **+**. However,
-    according to `PEP 3101 <http://www.python.org/dev/peps/pep-3101/>`_,
-    **%** operator became deprecated in Python 3.1 and will be replaced by the
-    **format()** method in the later versions.
+    according to :pep:`3101`, the **%** operator became deprecated in
+    Python 3.1 and will be replaced by the **format()** method in the later versions.
 
 .. code-block:: python
 

docs/writing/style.rst

@@ -117,8 +117,8 @@ follow the syntax that is the closest to the function definition: ``send('Hello'
 'World', cc='Cthulhu', bcc='God')``.
 
 As a side note, following `YAGNI <http://en.wikipedia.org/wiki/You_ain't_gonna_need_it>`_
-principle, it is often harder to remove an optional argument (and its logic inside the 
-function) that was added "just in case" and is seemingly never used, than to add a 
+principle, it is often harder to remove an optional argument (and its logic inside the
+function) that was added "just in case" and is seemingly never used, than to add a
 new optional argument and its logic when needed.
 
 3. The **arbitrary argument list** is the third way to pass arguments to a
@@ -256,14 +256,14 @@ are a probable indication that such a refactoring is needed.
 Idioms
 ------
 
-A programming idiom, put simply, is a *way* to write code. The notion of programming idioms 
+A programming idiom, put simply, is a *way* to write code. The notion of programming idioms
 is discussed amply at `c2 <http://c2.com/cgi/wiki?ProgrammingIdiom>`_ and at `Stack Overflow <http://stackoverflow.com/questions/302459/what-is-a-programming-idiom>`_.
 
-Idiomatic Python code is often referred to as being *Pythonic*. 
+Idiomatic Python code is often referred to as being *Pythonic*.
 
-Although there usually is one-- and preferably only one --obvious way to do it; 
+Although there usually is one-- and preferably only one --obvious way to do it;
 *the* way to write idiomatic Python code can be non-obvious to Python beginners. So,
-good idioms must be consciously acquired. 
+good idioms must be consciously acquired.
 
 Some common Python idioms follow:
 
@@ -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.
 
 ::
 
@@ -399,7 +399,7 @@ PEP 8
 
 PEP 8 is the de-facto code style guide for Python.
 
-    `PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_
+    :pep:`8`
 
 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
@@ -287,7 +287,7 @@ always returns the same result (but only for the duration of the test).
     # not where the SearchForm class itself is imported from
     @mock.patch('myapp.SearchForm.search', mock_search)
     def test_new_watchlist_activities(self):
-        # get_search_results runs a search and iterates over the result 
+        # get_search_results runs a search and iterates over the result
         self.assertEqual(len(myapp.get_search_results(q="fish")), 3)
 
 Mock has many other ways you can configure it and control its behavior.