From 13d99d95fe31b76d350ca74ae5163aaf73704c19 Mon Sep 17 00:00:00 2001 From: kuyan Date: Sat, 3 Aug 2013 19:28:48 -0700 Subject: [PATCH] Let Sphinx link to Python documentation. Instead of directly linking to the relevant passages. --- docs/writing/gotchas.rst | 8 ++++---- docs/writing/structure.rst | 11 ++++++----- docs/writing/style.rst | 23 ++++++++++------------- 3 files changed, 20 insertions(+), 22 deletions(-) diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst index d96d3d8..98bfd2c 100644 --- a/docs/writing/gotchas.rst +++ b/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 ` +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 diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 3ec2cf1..9bb685c 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -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:`% ` 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 diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 4900459..57a814e 100644 --- a/docs/writing/style.rst +++ b/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 `_ 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 `_ 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 `_ -provide a powerful, concise way to work with lists. Also, the `map -`_ and `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 `_ 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 ~~~~~~~~~~~~~~~~