Use the :pep: tag instead of directly linking PEPs

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,
-open a file called `.vimrc` and add the following lines:::
+: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
     set shiftwidth=4  " operation >> indents 4 columns; << unindents 4 columns

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/learning.rst

@@ -65,7 +65,7 @@ Python Koans
 
 Python Koans is a port of Edgecase's Ruby Koans.  It uses a test-driven
 approach, q.v. TEST DRIVEN DESIGN SECTION to provide an interactive tutorial
-teaching basic python concepts.  By fixing assertion statements that fail in a 
+teaching basic python concepts.  By fixing assertion statements that fail in a
 test script, this provides sequential steps to learning python.
 
 For those used to languages and figuring out puzzles on their own, this can be
@@ -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/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").
-
-.. _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.