More doc formatting tweaks

edschofield · edschofield · commit b4d4480b0f3d · 2013-09-25T23:44:09.000+10:00
diff --git a/docs/source/automatic_conversion.rst b/docs/source/automatic_conversion.rst
@@ -3,10 +3,11 @@
 Automatic conversion with ``futurize``
 ======================================
 
-The ``future`` source tree includes an experimental script called ``futurize``
-to aid in making either Python 2 code or Python 3 code compatible with both
-platforms using the ``future`` module. It is based on 2to3 and uses fixers from
-``lib2to3``, ``lib3to2``, and ``python-modernize``.
+The ``future`` source tree includes an experimental script called
+``futurize`` to aid in making either Python 2 code or Python 3 code
+compatible with both platforms using the :mod:`future` module. It is
+based on 2to3 and uses fixers from ``lib2to3``, ``lib3to2``, and
+``python-modernize``.
 
 For Python 2 code (the default), it runs the code through all the
 appropriate 2to3 fixers to turn it into valid Python 3 code, and then
@@ -42,6 +43,8 @@ into this code which runs on both Py2 and Py3::
     print('Hello', end=' ')
 
 
+To write out all the changes to your Python files that ``futurize`` suggests, use the ``-w`` flag.
+
 .. _backwards-conversion:
 
 Backwards: 3 to both
@@ -69,10 +72,12 @@ into this code which runs on both Py2 and Py3::
 Notice that in both cases ``futurize`` forces a new-style class and
 imports the renamed stdlib module under its Py3 name.
 
-It also handles the following Python 3 features:
+``futurize --from3`` also handles the following Python 3 features:
 
 - keyword-only arguments
-- metaclasses (using ``future.utils.with_metaclass``)
+- metaclasses (using :func:`~future.utils.with_metaclass`)
+- function annotations (PEP 3107)
+- extended tuple unpacking (PEP 3132)
 
 
 How well does ``futurize`` work?
diff --git a/docs/source/bind_method.rst b/docs/source/bind_method.rst
@@ -1,10 +1,12 @@
+.. _bind-method:
+
 Binding a method to a class
 ---------------------------
 
-Python 2 draws a distinction between bound and unbound methods, whereas in Python
-3 this distinction is gone: unbound methods have been removed from the
-language. To bind a method to a class compatibly across Python 3 and Python 2,
-you can use this helper function::
+Python 2 draws a distinction between bound and unbound methods, whereas
+in Python 3 this distinction is gone: unbound methods have been removed
+from the language. To bind a method to a class compatibly across Python
+3 and Python 2, you can use this helper function::
 
     from future.utils import bind_method
     
@@ -20,8 +22,8 @@ you can use this helper function::
     g.greet('Hi!')
 
 
-On Python 3, calling ``bind_method(cls, name, func)`` is equivalent to calling
-``setattr(cls, name, func)``. On Python 2 it is equivalent to::
+On Python 3, calling ``bind_method(cls, name, func)`` is equivalent to
+calling ``setattr(cls, name, func)``. On Python 2 it is equivalent to::
     
     import types
     setattr(cls, name, types.MethodType(func, None, cls))
diff --git a/docs/source/bytes_object.rst b/docs/source/bytes_object.rst
@@ -3,23 +3,23 @@
 bytes
 -----
 
-Handling ``bytes`` consistently and correctly has traditionally been one of the
-most difficult tasks in writing a Py3/2 compatible codebase. This is because
-the Python 2 ``bytes`` object is simply an alias for Python 2's ``str``, rather
-than a true implementation of the Python 3 ``bytes`` object, which is
-substantially different.
-
-``future`` contains a backport of the ``bytes`` object from Python 3 which
-passes most of the Python 3 tests for ``bytes``. (See
+Handling ``bytes`` consistently and correctly has traditionally been one
+of the most difficult tasks in writing a Py3/2 compatible codebase. This
+is because the Python 2 :class:`bytes` object is simply an alias for
+Python 2's :class:`str`, rather than a true implementation of the Python
+3 :class:`bytes` object, which is substantially different.
+
+``future`` contains a backport of the :mod:`bytes` object from Python 3
+which passes most of the Python 3 tests for :mod:`bytes`. (See
 :ref:`bytes-test-results`.) You can use it as follows::
 
     from future.builtins import bytes
     
     b = bytes(b'ABCD')
 
-On Py2, this object inherits from Python 2's native ``str``, but it enforces
-the much stricter separation from unicode strings that Python 3's ``bytes``
-requires::
+On Py2, this object inherits from Python 2's :class:`str`, but it
+enforces the much stricter separation from unicode strings that Python
+3's :class:`bytes` requires::
 
     >>> b + u'EFGH'      # TypeError
     Traceback (most recent call last):
@@ -31,16 +31,17 @@ requires::
       File "<stdin>", line 1, in <module>
     TypeError: sequence item 0: expected bytes, found unicode string
 
-In most other ways, these ``bytes`` objects have identical behaviours to Python 3's ``bytes``::
+In most other ways, these :class:`bytes` objects have identical
+behaviours to Python 3's :class:`bytes`::
 
     b = bytes(b'ABCD')
     assert list(b) == [65, 66, 67, 68]
     assert repr(b) == "b'ABCD'"
     assert b.split(b'b') == [b'A', b'CD']
 
-Currently the easiest way to ensure identical use of byte-strings compatibly between
-Python 3 and 2 is to wrap all byte-string literals ``b'...'`` in a ``bytes()``
-call, as follows::
+Currently the easiest way to ensure identical use of byte-strings
+compatibly between Python 3 and 2 is to wrap all byte-string literals
+``b'...'`` in a :func:`~bytes()`` call, as follows::
     
     from future.builtins import *
     
@@ -50,30 +51,30 @@ call, as follows::
 
     # ...
 
-This is not perfect, but it is superior to manually debugging and fixing code
-incompatibilities caused by the many differences between Py3 bytes and Py2
-strings.
+This is not perfect, but it is superior to manually debugging and fixing
+code incompatibilities caused by the many differences between Py3 bytes
+and Py2 strings.
 
 
 .. _bytes-test-results:
 
 Test results
 ~~~~~~~~~~~~
 
-For reference, when not using the backported ``bytes`` object, running the Py3.3
-``bytes`` unit tests in ``test_bytes.py`` on Py2 (after fixing imports) gives
-this::
+For reference, when not using the backported :class:`bytes` object,
+running the Py3.3 ``bytes`` unit tests in ``test_bytes.py`` on Py2 (after
+fixing imports) gives this::
 
     --------------------------------------------------------------
     Ran 203 tests in 0.209s
     
     FAILED (failures=31, errors=55, skipped=1)
     --------------------------------------------------------------
 
-The ``future`` backport of the Py3 ``bytes`` object passes most of the Python 3
-tests for ``bytes`` on Py2, except those requiring specific wording in exception
-messages.
+The ``future`` backport of the Py3 :class:`bytes` object passes most of
+the Python 3 tests for ``bytes`` on Py2, except those requiring specific
+wording in exception messages.
 
-See ``future/tests/test_bytes.py`` in the source for the unit tests that are
-actually run.
+See ``future/tests/test_bytes.py`` in the source for the unit tests that
+are actually run.
 
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
@@ -1,5 +1,5 @@
-FAQ
-***
+Frequently Asked Questions (FAQ)
+********************************
 
 Who is this for?
 ================
diff --git a/docs/source/future_imports.rst b/docs/source/future_imports.rst
@@ -6,7 +6,8 @@ Imports
 future imports
 ~~~~~~~~~~~~~~
 
-The imports to include at the top of every future-compatible Py3/2 module are::
+The imports to include at the top of every future-compatible Py3/2
+module are::
 
     from __future__ import (absolute_import, division,
                             print_function, unicode_literals)
@@ -29,8 +30,8 @@ explicit form.)
 __future__ imports
 ~~~~~~~~~~~~~~~~~~
 
-For more information about the ``__future__`` imports, which are a standard
-feature of Python, see the following docs:
+For more information about the ``__future__`` imports, which are a
+standard feature of Python, see the following docs:
 
 - absolute_import: `PEP 328: Imports: Multi-Line and Absolute/Relative <http://www.python.org/dev/peps/pep-0328>`_
 - division: `PEP 238: Changing the Division Operator <http://www.python.org/dev/peps/pep-0238>`_
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,9 +1,10 @@
 future: clean single-source support for Python 3 and 2
 ======================================================
 
-``future`` is the missing compatibility layer between Python 3 and Python 2. It
-allows you to maintain a single, clean Python 3.x-compatible codebase with
-minimal cruft and also run it on Python 2 without further modification.
+``future`` is the missing compatibility layer between Python 3 and
+Python 2. It allows you to maintain a single, clean Python
+3.x-compatible codebase with minimal cruft and also run it on Python 2
+without further modification.
 
 It is designed to be used together with Python's built-in ``__future__``
 imports like this::
@@ -17,19 +18,5 @@ followed by standard Python 3 code, which then runs unchanged on both
 Python 3 and Python 2.7. For examples, see the :ref:`overview`.
 
 
-**Features:**
-
--   backports or remappings for 15 builtins with different semantics on Py3 versus Py2
--   supports the reorganized Py3 standard library interface
--   220+ unit tests
--   clean on Py3: ``future`` imports and decorators have no effect on Py3 (and
-	no namespace pollution)
--   ``futurize`` script for automatic conversion from either Py2 or Py3 to a
-	clean single-source codebase compatible with both Py3 and Py2
--   a consistent set of utility functions and decorators selected from
-	Py2/3 compatibility interfaces from projects like six, IPython, Jinja2,
-	Django, and Pandas.
-
-
 .. include:: contents.rst.inc
 
diff --git a/docs/source/overview.rst b/docs/source/overview.rst
@@ -3,27 +3,46 @@
 Overview
 ========
 
-``future`` is the missing compatibility layer between Python 3 and Python 2. It
-allows you to maintain a single, clean Python 3.x-compatible codebase with
-minimal cruft and run it easily on Python 2 without further modification.
+``future`` is the missing compatibility layer between Python 3 and Python
+2. It allows you to maintain a single, clean Python 3.x-compatible
+codebase with minimal cruft and run it easily on Python 2 without further
+modification.
 
-It is designed to be used together with Python's built-in ``__future__``
-imports like this::
+.. _features:
+
+**Features:**
+
+-   backports or remappings for 15 builtins with different semantics on
+	Py3 versus Py2
+-   supports the reorganized Py3 standard library interface
+-   220+ unit tests
+-   clean on Py3: ``future`` imports and decorators have no effect on Py3
+	(and no namespace pollution)
+-   ``futurize`` script for automatic conversion from either Py2 or Py3
+	to a clean single-source codebase compatible with both Py3 and Py2
+-   a consistent set of utility functions and decorators selected from
+	Py2/3 compatibility interfaces from projects like six, IPython,
+	Jinja2, Django, and Pandas.
 
-    from __future__ import (absolute_import, division,
-                            print_function, unicode_literals)
-    from future import standard_library
-    from future.builtins import *
-    
-followed by standard Python 3 code, which then runs unchanged on both
-Python 3 and Python 2.7.
 
 .. _code-examples:
 
 Code examples
 -------------
 
-After the imports above, this code runs identically on Python 3 and 2::
+``future`` is designed to be imported at the top of each Python module
+together with Python's built-in ``__future__`` module like this::
+
+    from __future__ import (absolute_import, division,
+                            print_function, unicode_literals)
+    from future import standard_library
+    from future.builtins import *
+    
+followed by standard Python 3 code. The imports allow this code to run
+unchanged on Python 3 and Python 2.7.
+
+For example, after these imports, this code runs identically on Python 3
+and 2.7::
     
     # Support for renamed standard library modules via import hooks
     from http.client import HttpConnection
diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
diff --git a/docs/source/what_else.rst b/docs/source/what_else.rst
