Merge pull request #74 from QuLogic/doc-fix

edschofield · edschofield · commit 2bd868123514 · 2014-06-20T13:49:46.000+10:00
Small doc fixes
diff --git a/README.rst b/README.rst
@@ -163,8 +163,6 @@ the top of each module.
 In both cases, the result should be relatively clean Py3-style code that runs
 mostly unchanged on both Python 2 and Python 3.
 
-.. _forwards-conversion:
-
 Futurize: 2 to both
 ~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -315,8 +315,8 @@ As usual, this feature has no effect on Python 3.
 
 
 
-Utility functions raise_ and exec_
-----------------------------------
+Utility functions ``raise_`` and ``exec_``
+------------------------------------------
 
 The functions ``raise_with_traceback()`` and ``raise_()`` were
 added to ``future.utils`` to offer either the Python 3.x or Python 2.x
@@ -463,19 +463,19 @@ v0.11.4:
 
 v0.11.3:
   * The ``futurize`` and ``pasteurize`` scripts add an explicit call to
-  ``future.standard_library.install_hooks()`` whenever modules affected by PEP
-  3108 are imported.
+    ``future.standard_library.install_hooks()`` whenever modules affected by
+    PEP 3108 are imported.
 
   * The ``future.builtins.bytes`` constructor now accepts ``frozenset``
-  objects as on Py3.
+    objects as on Py3.
 
 v0.11.2:
   * The ``past.autotranslate`` feature now finds modules to import more
-  robustly and works with Python eggs.
+    robustly and works with Python eggs.
 
 v0.11.1:
   * Update to ``requirements_py26.txt`` for Python 2.6. Small updates to
-  docs and tests.
+    docs and tests.
 
 v0.11:
   * New ``past`` package with ``past.builtins`` and ``past.translation``
diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc
@@ -12,7 +12,7 @@ Contents:
    what_else
    automatic_conversion
    porting
-   standard_library_incompatibilities
+   stdlib_incompatibilities
    faq
    changelog
    credits
diff --git a/docs/conversion_limitations.rst b/docs/conversion_limitations.rst
@@ -15,12 +15,12 @@ Contributions to the ``lib2to3``-based fixers for ``futurize`` and
 ``pasteurize`` are particularly welcome! Please see :ref:`contributing`.
 
 
-.. _futurize-limitations
+.. _futurize-limitations:
 
 Known limitations
 -----------------
 
-``futurize`` doesn't currently make this change automatically::
+``futurize`` doesn't currently make this change automatically:
 
 1. Strings containing ``\U`` produce a ``SyntaxError`` on Python 3. An example is::
 
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -234,7 +234,7 @@ fewer compatibility hacks.
 
 
 What is the relationship between ``python-future`` and ``python-modernize``?
------------------------------------------------------------------------
+----------------------------------------------------------------------------
 
 ``python-future`` contains, in addition to the ``future`` compatibility
 package, a ``futurize`` script that is similar to ``python-modernize.py``
@@ -257,7 +257,7 @@ Platform and version support
 .. _supported-versions:
 
 Which versions of Python does ``python-future`` support?
--------------------------------------------------
+--------------------------------------------------------
 
 Python 2.6, 2.7, and 3.3+ only.
 
@@ -289,7 +289,7 @@ and pull requests are welcome!
 
 
 Do you support IronPython and/or Jython?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Not sure. This would be nice...
 
diff --git a/docs/features_incomplete.rst b/docs/features_incomplete.rst
diff --git a/docs/imports.rst b/docs/imports.rst
@@ -3,7 +3,7 @@
 Imports
 =======
 
-.. ___future__-imports:
+.. _-__future__-imports:
 
 __future__ imports
 ------------------
diff --git a/docs/pasteurize.rst b/docs/pasteurize.rst
@@ -1,7 +1,7 @@
 .. _backwards-conversion:
 
 Pasteurize: 3 to both
---------------------
+---------------------
 
 Running ``pasteurize -w mypy3module.py`` turns this Python 3 code::
     
diff --git a/docs/roadmap.rst b/docs/roadmap.rst
@@ -5,14 +5,17 @@ futurize script
 ---------------
 
 1. "Safe" mode -- from Py2 to modern Py2 or Py3 to more-compatible Py3
+
    - Split the fixers into two categories: safe and bold
    - Safe is highly unlikely to break existing Py2 or Py3 support. The
      output of this still requires :mod:`future` imports. Examples:
-     - Compatible metaclass syntax on Py3
-     - Explicit inheritance from object on Py3
+
+      - Compatible metaclass syntax on Py3
+      - Explicit inheritance from object on Py3
     
    - Bold might make assumptions about which strings on Py2 should be
      unicode strings and which should be bytestrings.
+
      - We should also build up a database of which standard library
        interfaces on Py2 and Py3 accept unicode strings versus
        byte-strings, which have changed, and which haven't.
diff --git a/docs/standard_library_imports.rst b/docs/standard_library_imports.rst
@@ -52,8 +52,8 @@ One workaround is to replace the dot with an underscore::
 
     import future.moves.http.client as http_client
 
-import_ and from_import functions
----------------------------------
+``import_`` and ``from_import`` functions
+-----------------------------------------
 
 A third option, which also works with two-level imports, is to use the
 ``import_`` and ``from_import`` functions from ``future.standard_library`` as
diff --git a/docs/str_object.rst b/docs/str_object.rst
@@ -80,8 +80,8 @@ same behaviours as Python 3's :class:`str`::
     >>> assert s.split('B') == ['A', 'CD']
 
 .. If you must ensure identical use of (unicode) strings across Py3 and Py2 in a
-.. single-source codebase, you can wrap string literals in a :func:`~str` call, as
-..  follows::
+.. single-source codebase, you can wrap string literals in a :func:`~str` call,
+.. as follows::
 ..     
 ..     from __future__ import unicode_literals
 ..     from future.builtins import *
diff --git a/docs/translation.rst b/docs/translation.rst
@@ -84,7 +84,7 @@ This is a standard Python 3 data type, so, when called from Python 3 code,
     builtins.dict_keys
 
 
-.. _translation-limitations
+.. _translation-limitations:
 
 Known limitations of ``past.translation``
 *******************************************
diff --git a/docs/why_python3.rst b/docs/why_python3.rst
@@ -19,7 +19,7 @@ Why are Unicode strings better on Python 3?
 -------------------------------------------
 
 - it is not the default string type (you have to prefix the string
-with a u to get Unicode);
+  with a u to get Unicode);
 
 - it is missing some functionality, e.g. casefold;
 
@@ -30,7 +30,7 @@ with a u to get Unicode);
 - narrow builds take up to two times more memory per string as needed;
 
 - worse, narrow builds have very naive (possibly even "broken")
-handling of code points in the Supplementary Multilingual Planes.
+  handling of code points in the Supplementary Multilingual Planes.
 
 The unicode string type in Python 3 is better because:
 
@@ -39,10 +39,10 @@ The unicode string type in Python 3 is better because:
 - it includes more functionality;
 
 - starting in Python 3.3, it gets rid of the distinction between
-narrow and wide builds;
+  narrow and wide builds;
 
 - which reduces the memory overhead of strings by up to a factor
-of four in many cases;
+  of four in many cases;
 
 - and fixes the issue of SMP code points.
 
diff --git a/future/standard_library/__init__.py b/future/standard_library/__init__.py
@@ -389,7 +389,7 @@ def scrub_py2_sys_modules():
 def scrub_future_sys_modules():
     """
     On Py2 only: Removes any modules such as ``http`` and ``html.parser`` from
-    the ``sys.modules`` cache. Such modules would confuse code such as this:
+    the ``sys.modules`` cache. Such modules would confuse code such as this::
 
         # PyChecker does something like this:
         try:
@@ -399,21 +399,22 @@ def scrub_future_sys_modules():
         finally:
             PY3 = True
 
-    or this:
+    or this::
 
         import urllib       # We want this to pull in only the Py2 module
                             # after scrub_future_sys_modules() has been called
 
-    or this:
+    or this::
 
         # Requests does this in requests/packages/urllib3/connection.py:
         try: # Python 3
             from http.client import HTTPConnection, HTTPException
         except ImportError:
             from httplib import HTTPConnection, HTTPException
 
-    This function removes items matching this spec from sys.modules:
-        key: new_py3_module_name
+    This function removes items matching this spec from sys.modules::
+
+        key:   new_py3_module_name
         value: either future.backports module or py2 module with
                another name
     """
@@ -742,7 +743,9 @@ def from_import(module_name, *symbol_names, **kwargs):
     and this on Py2:
 
         >>> from future.moves.module_name import symbol_names[0], ...
+
     or:
+
         >>> from future.backports.module_name import symbol_names[0], ...
 
     except that it also handles dotted module names such as ``http.client``.
diff --git a/future/types/__init__.py b/future/types/__init__.py
@@ -82,7 +82,7 @@ def append(self, item):
 round()
 -------
 Python 3 modifies the behaviour of ``round()`` to use "Banker's Rounding".
-See http://stackoverflow.com/a/10825998_. See the ``newround`` module
+See http://stackoverflow.com/a/10825998. See the ``newround`` module
 docstring for more details.
 
 """
diff --git a/future/types/newrange.py b/future/types/newrange.py
@@ -28,7 +28,7 @@ class newrange(Sequence):
     """
     Pure-Python backport of Python 3's range object.  See `the CPython
     documentation for details:
-        <http://docs.python.org/py3k/library/functions.html#range>`_
+    <http://docs.python.org/py3k/library/functions.html#range>`_
     """
 
     def __init__(self, *args):
diff --git a/future/utils/__init__.py b/future/utils/__init__.py
@@ -2,32 +2,38 @@
 A selection of cross-compatible functions for Python 2 and 3.
 
 These come from several sources:
-* Jinja2 (BSD licensed: see https://github.com/mitsuhiko/jinja2/blob/master/LICENSE
-* Pandas compatibility module pandas.compat
-* six.py by Benjamin Peterson
-* Django
+
+    * Jinja2 (BSD licensed: see
+      https://github.com/mitsuhiko/jinja2/blob/master/LICENSE)
+    * Pandas compatibility module pandas.compat
+    * six.py by Benjamin Peterson
+    * Django
 
 This exports useful functions for 2/3 compatible code that are not
 builtins on Python 3:
-* bind_method: binds functions to classes
-* ``native_str_to_bytes`` and ``bytes_to_native_str``
-* ``native_str``: always equal to the native platform string object (because
-  this may be shadowed by imports from future.builtins)
-* lists: lrange(), lmap(), lzip(), lfilter()
-* iterable method compatibility: iteritems, iterkeys, itervalues
-  * Uses the original method if available, otherwise uses items, keys, values.
-* types:
-    * text_type: unicode in Python 2, str in Python 3
-    * binary_type: str in Python 2, bythes in Python 3
-    * string_types: basestring in Python 2, str in Python 3
-
-* bchr(c):
-    Take an integer and make a 1-character byte string
-* bord(c)
-    Take the result of indexing on a byte string and make an integer
-* tobytes(s)
-    Take a text string, a byte string, or a sequence of characters taken
-    from a byte string, and make a byte string.
+
+    * bind_method: binds functions to classes
+    * ``native_str_to_bytes`` and ``bytes_to_native_str``
+    * ``native_str``: always equal to the native platform string object (because
+      this may be shadowed by imports from future.builtins)
+    * lists: lrange(), lmap(), lzip(), lfilter()
+    * iterable method compatibility: iteritems, iterkeys, itervalues
+
+        * Uses the original method if available, otherwise uses items, keys, values.
+
+    * types:
+
+        * text_type: unicode in Python 2, str in Python 3
+        * binary_type: str in Python 2, bythes in Python 3
+        * string_types: basestring in Python 2, str in Python 3
+
+    * bchr(c):
+        Take an integer and make a 1-character byte string
+    * bord(c)
+        Take the result of indexing on a byte string and make an integer
+    * tobytes(s)
+        Take a text string, a byte string, or a sequence of characters taken
+        from a byte string, and make a byte string.
 
 This module also defines a simple decorator called
 ``python_2_unicode_compatible`` (from django.utils.encoding) which
