Merge pull request realpython#301 from kuyan/patch-1

More formatting fixes, link fixes

Author: Kenneth Reitz

docs/dev/env.rst

@@ -286,12 +286,11 @@ Other Tools
 IDLE
 ----
 
-`IDLE <http://docs.python.org/library/idle.html>`_ is an integrated
-development environment that is part of Python standard library. It is
-completely written in Python and uses the Tkinter GUI toolkit. Though IDLE
-is not suited for full-blown development using Python, it is quite
-helpful to try out small Python snippets and experiment with different
-features in Python.
+:ref:`IDLE <python:idle>` is an integrated development environment that is
+part of Python standard library. It is completely written in Python and uses
+the Tkinter GUI toolkit. Though IDLE is not suited for full-blown development
+using Python, it is quite helpful to try out small Python snippets and
+experiment with different features in Python.
 
 It provides the following features:
 

docs/scenarios/cli.rst

@@ -11,4 +11,6 @@ Clint
 docopt
 ------
 
-`docopt <http://docopt.org/>`_ is a lightweight, highly Pythonic package that allows creating command line interfaces easily and intuitively, by parsing POSIX-style usage instructions.
+`docopt <http://docopt.org/>`_ is a lightweight, highly Pythonic package that
+allows creating command line interfaces easily and intuitively, by parsing
+POSIX-style usage instructions.

docs/writing/gotchas.rst

@@ -65,7 +65,7 @@ What You Should Do Instead
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Create a new object each time the function is called, by using a default arg to
-signal that no argument was provided (``None`` is often a good choice).
+signal that no argument was provided (:py:data:`None` is often a good choice).
 
 .. code-block:: python
 
@@ -137,9 +137,9 @@ is looked up in the surrounding scope at call time. By then, the loop has
 completed and ``i`` is left with its final value of 4.
 
 What's particularly nasty about this gotcha is the seemingly prevalent
-misinformation that this has something to do with ``lambda``\s in Python.
-Functions created with a ``lambda`` expression are in no way special, and in
-fact the same exact behavior is exhibited by just using an ordinary ``def``:
+misinformation that this has something to do with :ref:`lambdas <python:lambda>`
+in Python. Functions created with a ``lambda`` expression are in no way special,
+and in fact the same exact behavior is exhibited by just using an ordinary ``def``:
 
 .. code-block:: python
 

docs/writing/structure.rst

@@ -83,7 +83,7 @@ while another would handle low-level manipulation of data. The most natural way
 to separate these two layers is to regroup all interfacing functionality
 in one file, and all low-level operations in another file. In this case,
 the interface file needs to import the low-level file. This is done with the
-`import` and `from ... import` statements.
+``import`` and ``from ... import`` statements.
 
 As soon as you use `import` statements you use modules. These can be either built-in
 modules such as `os` and `sys`, third-party modules you have installed in your
@@ -106,7 +106,7 @@ Aside for some naming restrictions, nothing special is required for a Python fil
 to be a module, but the import mechanism needs to be understood in order to use
 this concept properly and avoid some issues.
 
-Concretely, the `import modu` statement will look for the proper file, which is
+Concretely, the ``import modu`` statement will look for the proper file, which is
 `modu.py` in the same directory as the caller if it exists.  If it is not
 found, the Python interpreter will search for `modu.py` in the "path"
 recursively and raise an ImportError exception if it is not found.
@@ -120,20 +120,20 @@ Then, the module's variables, functions, and classes will be available to the ca
 through the module's namespace, a central concept in programming that is
 particularly helpful and powerful in Python.
 
-In many languages, an `include file` directive is used by the preprocessor to
+In many languages, an ``include file`` directive is used by the preprocessor to
 take all code found in the file and 'copy' it into the caller's code. It is
 different in Python: the included code is isolated in a module namespace, which
 means that you generally don't have to worry that the included code could have
 unwanted effects, e.g. override an existing function with the same name.
 
 It is possible to simulate the more standard behavior by using a special syntax
-of the import statement: `from modu import *`. This is generally considered bad
-practice. **Using `import *` makes code harder to read and makes dependencies less
+of the import statement: ``from modu import *``. This is generally considered bad
+practice. **Using ``import *`` makes code harder to read and makes dependencies less
 compartmentalized**.
 
-Using `from modu import func` is a way to pinpoint the function you want to
-import and put it in the global namespace. While much less harmful than `import
-*` because it shows explicitly what is imported in the global namespace, its
+Using ``from modu import func`` is a way to pinpoint the function you want to
+import and put it in the global namespace. While much less harmful than ``import
+*`` because it shows explicitly what is imported in the global namespace, its
 advantage over a simpler `import modu` is only that it will save some typing.
 
 **Very bad**
@@ -166,7 +166,7 @@ Python. Readability means to avoid useless boilerplate text and clutter,
 therefore some efforts are spent trying to achieve a certain level of brevity.
 But terseness and obscurity are the limits where brevity should stop. Being
 able to tell immediately where a class or function comes from, as in the
-`modu.func` idiom, greatly improves code readability and understandability in
+``modu.func`` idiom, greatly improves code readability and understandability in
 all but the simplest single file projects.
 
 
@@ -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 :py:meth:`list.append` or :py:meth:`list.pop`, and
 can be modified in place. The same goes for dictionaries.
 
 Immutable types provide no method for changing their content.
@@ -464,10 +464,11 @@ should be your preferred method.
     foo = ''.join([foo, 'ooo'])
 
 .. note::
-    You can also use the ``%`` formatting operator to concatenate the
-    pre-determined number of strings besides ``join()`` and ``+``. However,
-    according to :pep:`3101`, the ``%`` operator became deprecated in
-    Python 3.1 and will be replaced by the ``format()`` method in the later versions.
+    You can also use the :ref:`% <python:string-formatting>` formatting operator
+    to concatenate a pre-determined number of strings besides :py:meth:`str.join`
+    and ``+``. However, according to :pep:`3101`, the ``%`` operator became
+    deprecated in Python 3.1 and will be replaced by the :py:meth:`str.format`
+    method in the later versions.
 
 .. code-block:: python
 

docs/writing/style.rst

@@ -335,7 +335,7 @@ Instead, use a list comprehension:
     four_lists = [[] for __ in xrange(4)]
 
 
-A common idiom for creating strings is to use `join <http://docs.python.org/library/string.html#string.join>`_ on an empty string.::
+A common idiom for creating strings is to use :py:meth:`str.join` on an empty string.::
 
     letters = ['s', 'p', 'a', 'm']
     word = ''.join(letters)
@@ -433,7 +433,7 @@ Check if variable equals a constant
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You don't need to explicitly compare a value to True, or None, or 0 - you can
-just add it to the if statement. See `Truth Value Testing
+just add it to the if statement. See :ref:`Truth Value Testing
 <http://docs.python.org/library/stdtypes.html#truth-value-testing>`_ for a
 list of what is considered false.
 
@@ -466,8 +466,8 @@ list of what is considered false.
 Access a Dictionary Element
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Don't use the ``has_key`` function. Instead use ``x in d`` syntax, or pass
-a default argument to ``get``.
+Don't use the :py:meth:`dict.has_key` method. Instead, use ``x in d`` syntax,
+or pass a default argument to :py:meth:`dict.get`.
 
 **Bad**:
 
@@ -497,10 +497,9 @@ Short Ways to Manipulate Lists
 
 `List comprehensions
 <http://docs.python.org/tutorial/datastructures.html#list-comprehensions>`_
-provide a powerful, concise way to work with lists. Also, the `map
-<http://docs.python.org/library/functions.html#map>`_ and `filter
-<http://docs.python.org/library/functions.html#filter>`_ functions can perform
-operations on lists using a different concise syntax.
+provide a powerful, concise way to work with lists. Also, the :py:func:`map`
+:py:func:`filter` functions can perform operations on lists using a different,
+more concise syntax.
 
 **Bad**:
 
@@ -540,8 +539,7 @@ operations on lists using a different concise syntax.
     # Or:
     a = map(lambda i: i + 3, a)
 
-Use `enumerate <http://docs.python.org/library/functions.html#enumerate>`_ to
-keep a count of your place in the list.
+Use :py:func:`enumerate` keep a count of your place in the list.
 
 .. code-block:: python
 
@@ -552,9 +550,8 @@ keep a count of your place in the list.
     # 1 4
     # 2 5
 
-The ``enumerate`` function has better readability than handling a counter
-manually. Moreover,
-it is better optimized for iterators.
+The :py:func:`enumerate` function has better readability than handling a
+counter manually. Moreover, it is better optimized for iterators.
 
 Read From a File
 ~~~~~~~~~~~~~~~~

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