Update docs

Author: edschofield

README.rst

@@ -205,11 +205,7 @@ into this code which runs on both Py2 and Py3:
     name = input()
     greet(name)
 
-
-For complex projects, it may be better to divide the porting into two stages.
-``futurize`` supports a ``--stage1`` flag for safe changes that modernize the
-code but do not break Python 2.6 compatibility or introduce a depdendency on the
-``future`` package. Calling ``futurize --stage2`` then completes the process.
+See :ref:`forwards-conversion` and :ref:`backwards-conversion` for more details.
 
 
 Automatic translation

docs/credits.rst

@@ -61,6 +61,8 @@ Patches
 - German Larrain
 - Chris Lasher
 - Elliott Sales de Andrade
+- Tim Shaffer
+- Daniel Szoska
 - Jeff Tratner
 - Mystic-Mirage (GitHub)
 - str4d (GitHub)

docs/faq.rst

@@ -177,13 +177,11 @@ most inputs; worse, it allows arbitrary code execution by the user
 for specially crafted inputs because of the ``eval()`` executed by Python
 2's ``input()`` function.
 
-This is not an isolated example; almost every output of ``2to3`` will
-need modification to provide backward compatibility with Python 2.
-``future`` is designed for just this purpose.
-
-The ``future`` source tree contains a script called ``futurize`` that is
-based on ``lib2to3``. It is designed to turn either Python 2-only or
-Python 3-only code into code that is compatible with both platforms.
+This is not an isolated example; almost every output of ``2to3`` will need
+modification to provide backward compatibility with Python 2. As an
+alternative, the ``python-future`` project provides a script called
+``futurize`` that is based on ``lib2to3`` but will produce code that is
+compatible with both platforms (Py2 and Py3).
 
 
 Can I maintain a Python 2 codebase and use 2to3 to automatically convert to Python 3 in the setup script?

docs/futurize.rst

@@ -3,57 +3,7 @@
 Futurize: 2 to both
 --------------------
 
-For example, running ``futurize`` turns this Python 2 code:
-
-.. code-block:: python
-
-    import ConfigParser                 # Py2 module name
-
-    class Upper(object):
-        def __init__(self, iterable):
-            self._iter = iter(iterable)
-        def next(self):                 # Py2-style iterator interface
-            return next(self._iter).upper()
-        def __iter__(self):
-            return self
-
-    itr = Upper('hello')
-    print next(itr),
-    for letter in itr:
-        print letter,                   # Py2-style print statement
-
-into this code which runs on both Py2 and Py3:
-
-.. code-block:: python
-
-    from __future__ import print_function
-    from future import standard_library
-    standard_library.install_hooks()
-    from future.builtins import next
-    from future.builtins import object
-    import configparser                 # Py3-style import
-
-    class Upper(object):
-        def __init__(self, iterable):
-            self._iter = iter(iterable)
-        def __next__(self):             # Py3-style iterator interface
-            return next(self._iter).upper()
-        def __iter__(self):
-            return self
-
-    itr = Upper('hello')
-    print(next(itr), end=' ')           # Py3-style print function
-    for letter in itr:
-        print(letter, end=' ')
-
-
-To write out all the changes to your Python files that ``futurize`` suggests,
-use the ``-w`` flag.
-
-For complex projects, it is probably best to divide the porting into two stages.
-Stage 1 is for "safe" changes that modernize the code but do not break Python
-2.6 compatibility or introduce a depdendency on the ``future`` package. Stage 2
-is to complete the process.
+.. include:: futurize_overview.rst
 
 
 .. _forwards-conversion-stage1:
@@ -157,16 +107,16 @@ The complete set of fixers applied by ``futurize --stage1`` is:
     libfuturize.fixes.fix_raise
 
 
-Not applied:
+The following fixers from ``lib2to3`` are not applied:
 
 .. code-block:: python
 
     lib2to3.fixes.fix_import
 
-The ``fix_absolute_import`` fixer in`` libfuturize.fixes`` is applied instead of
-this. The new fixer both makes implicit relative imports explicit and
-adds the declaration ``from __future__ import absolute_import`` at the top
-of each relevant module.
+The ``fix_absolute_import`` fixer in ``libfuturize.fixes`` is applied instead of
+``lib2to3.fixes.fix_import``. The new fixer both makes implicit relative
+imports explicit and adds the declaration ``from __future__ import
+absolute_import`` at the top of each relevant module.
 
 .. code-block:: python
 
@@ -208,7 +158,7 @@ This converts ``set([1, 2, 3]``) to ``{1, 2, 3}``, breaking Python 2.6 support.
     lib2to3.fixes.fix_ws_comma
 
 This performs cosmetic changes. This is not applied by default because it
-does not serve improve Python 2/3 compatibility. (In some cases it may
+does not serve to improve Python 2/3 compatibility. (In some cases it may
 also reduce readability: see issue #58.)
 
 
@@ -272,7 +222,7 @@ becomes::
     standard_library.install_hooks()
     import configparser
 
-A complete list of fixers applied in Stage 2 is::
+The complete list of fixers applied in Stage 2 is::
 
     lib2to3.fixes.fix_basestring
     lib2to3.fixes.fix_dict
@@ -321,8 +271,7 @@ Not applied::
 
 Fixes applied with the ``futurize --conservative`` option::
 
-    libfuturize.fixes.fix_division_safe
-    (instead of libfuturize.fixes.fix_division).
+    libfuturize.fixes.fix_division_safe    # instead of libfuturize.fixes.fix_division.
 
 
 

docs/quickstart.rst

@@ -77,7 +77,9 @@ See :ref:`backwards-conversion` for more details.
 To convert existing Python 2 code
 ---------------------------------
 
-Start with this page: :ref:`automatic-conversion`.
+.. include:: futurize_overview.rst
+
+See :ref:`forwards-conversion-stage1` and :ref:`forwards-conversion-stage2` for more details.
 
 .. If you already know Python 3, start with the :ref:`automatic-conversion` page.
 .. If you don't know Python 3 yet, start with :ref:`python3-essentials`.
@@ -153,6 +155,7 @@ For more information on the automatic translation feature, see :ref:`translation
 
 Next steps
 ----------
-For more information about writing Py2/3-compatible code, see
-:ref:`compatible-idioms` and :ref:`what-else`.
+For more information about writing Py2/3-compatible code, see:
 
+- :ref:`compatible-idioms`
+- :ref:`what-else`.

docs/standard_library_imports.rst

@@ -10,13 +10,13 @@ modules from Python 3.3 (``future.backports``).
 
 There are currently four interfaces to the reorganized standard library.
 
-
 Context-manager interface
 -------------------------
+
 The recommended interface is via a context-manager called ``hooks``::
 
-    from future import standard_library
-    with standard_library.hooks():
+    from future.standard_library import hooks
+    with hooks():
         import socketserver
         import queue
         import configparser
@@ -55,7 +55,7 @@ One workaround is to replace the dot with an underscore::
 ``import_`` and ``from_import`` functions
 -----------------------------------------
 
-A third option, which also works with two-level imports, is to use the
+A third interface, which also works with two-level imports, is to use the
 ``import_`` and ``from_import`` functions from ``future.standard_library`` as
 follows::
 
@@ -117,7 +117,7 @@ modules on Py2::
 List of standard library modules
 --------------------------------
 
-The modules available from ``future.moves`` via one of the interfaces above are::
+The complete list of modules available via one of the four interfaces above is::
 
     import socketserver
     import queue
@@ -178,13 +178,11 @@ available independently of the python-future project::
     import pathlib                    # pip install pathlib
 
 A few modules from Python 3.4 and 3.3 are also available in the ``backports``
-package namespace::
+package namespace after ``pip install backports.lzma`` etc.::
 
     from backports import lzma
     from backports import functools_lru_cache as lru_cache
 
-After ``pip install backports.lzma`` etc.
-
 The following Python 2.6 backports of standard library packages from Python 2.7+
 are also available::
 

docs/whatsnew.rst

@@ -1,19 +1,22 @@
 .. _whats-new-0.13.x:
 
+What's New
+**********
+
 What's new in version 0.13.1
-****************************
+============================
 
 This is a minor bug-fix release.
 
 - Fix ``futurize --all-imports`` (issue #101)
 - Fix ``futurize --output-dir`` logging (issue #102)
 - Fix (multiple) inheritance of ``future.builtins.object`` with metaclasses (issues #91 and #96)
 - Fix ``futurize``'s refactoring of ``urllib`` imports (issue #94)
-- Doc formatting fixes (issues #98, 100)
+- Doc formatting fix (issues #98, 100)
 
 
-What's New in v0.13
-*******************
+What's new in version 0.13
+==========================
 
 This is mostly a clean-up release. It adds some small new compatibility features
 and fixes several bugs.
@@ -59,6 +62,6 @@ Bug fixes
 
 
 Previous versions
------------------
+=================
 
 See the :ref:`whats-old` for versions prior to v0.13.