diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 7d43991ab..81da462b0 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -286,12 +286,11 @@ Other Tools IDLE ---- -`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. +:ref:`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: diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst index 2416125f7..546eae017 100644 --- a/docs/scenarios/cli.rst +++ b/docs/scenarios/cli.rst @@ -11,4 +11,6 @@ Clint docopt ------ -`docopt `_ is a lightweight, highly Pythonic package that allows creating command line interfaces easily and intuitively, by parsing POSIX-style usage instructions. +`docopt `_ is a lightweight, highly Pythonic package that +allows creating command line interfaces easily and intuitively, by parsing +POSIX-style usage instructions. \ No newline at end of file diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst index d96d3d848..98bfd2c47 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 465097bfb..9bb685c6b 100644 --- a/docs/writing/structure.rst +++ b/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:`% ` 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 49004592f..57a814eed 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 ~~~~~~~~~~~~~~~~ diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index a5ac785d0..43504cdaf 100644 --- a/docs/writing/tests.rst +++ b/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