More doc updates

Author: edschofield

docs/automatic_conversion.rst

@@ -1,7 +1,7 @@
 .. _automatic-conversion:
 
-Automatic conversion to Py2/3 with ``futurize`` and ``pasteurize``
-==================================================================
+Automatic conversion to Py2&3
+=============================
 
 The ``future`` source tree includes scripts called ``futurize`` and
 ``pasteurize`` to aid in making Python 2 code or Python 3 code compatible with

docs/conf.py

@@ -110,7 +110,7 @@
     #'navbar_title': "Python-Future",
 
     # Tab name for entire site. (Default: "Site")
-    'navbar_site_name': "All pages",
+    'navbar_site_name': "Contents",
 
     # A list of tuples containing pages or urls to link to.
     # Valid tuples should be in the following forms:
@@ -121,19 +121,20 @@
     # an arbitrary url.
     'navbar_links': [
         ("Overview", "overview"),
+        ("Cheat Sheet", "compatible_idioms.html", True),
         ("FAQ", "faq.html", True),
         # ("Link", "http://example.com", True),
     ],
 
     # Render the next and previous page links in navbar. (Default: true)
-    'navbar_sidebarrel': True,
+    'navbar_sidebarrel': False,
 
     # Render the current pages TOC in the navbar. (Default: true)
     'navbar_pagenav': True,
 
     # Global TOC depth for "site" navbar tab. (Default: 1)
     # Switching to -1 shows all levels.
-    'globaltoc_depth': 2,
+    'globaltoc_depth': 3,
 
     # Include hidden TOCs in Site navbar?
     #
@@ -224,10 +225,10 @@
 #html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+html_show_sourcelink = False
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
+html_show_sphinx = False
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
 #html_show_copyright = True

docs/contents.rst.inc

@@ -4,8 +4,8 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
-   overview
    whatsnew
+   overview
    quickstart
    compatible_idioms
    imports

docs/credits.rst

@@ -55,6 +55,7 @@ Patches
 - Nicolas Delaby
 - Corey Farwell
 - Eric Firing
+- Alexey Kotlyarov
 - Lion Krischer
 - Marcin Kuzminski
 - Joshua Landau
@@ -66,6 +67,7 @@ Patches
 - Jeff Tratner
 - Mystic-Mirage (GitHub)
 - str4d (GitHub)
+- 9seconds (GitHub)
 
 Suggestions and Feedback
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -94,8 +96,8 @@ Other Credits
 - The ``raise_`` and ``raise_with_traceback`` functions were contributed by
   Jeff Tratner.
 
-- Documentation is generated with ``sphinx`` using the ``sphinx-bootstrap``
-  theme.
+- Documentation is generated with `Sphinx <http://sphinx.pocoo.org>`_ using the
+  ``sphinx-bootstrap`` theme.
 
 - ``past.translation`` is inspired by and borrows some code from Sanjay Vinip's
   ``uprefix`` module.

docs/faq.rst

@@ -28,7 +28,7 @@ Python 3.x is a better language and better set of standard libraries than
 Python 2.x in many ways. Python 3.x is cleaner, less warty, and easier to
 learn than Python 2. It has better memory efficiency, easier Unicode handling,
 and powerful new features like the `asyncio
-<https://pypi.python.org/pypi/asyncio>`_ module.
+<https://docs.python.org/3/library/asyncio.html>`_ module.
 
 .. Unicode handling is also much easier. For example, see `this page
 .. <http://pythonhosted.org/kitchen/unicode-frustrations.html>`_
@@ -115,8 +115,8 @@ community to remain united around a single version of the language.
 Maturity
 ========
 
-Is it tested?
--------------
+How well has it been tested?
+----------------------------
 
 ``future`` is used by several major projects, including `mezzanine
 <http://mezzanine.jupo.org>`_ and `ObsPy <http://www.obspy.org>`_. It is also
@@ -129,7 +129,7 @@ from the Python 3.3 test suite.
 In general, the ``future`` package itself is in good shape, whereas the
 ``futurize`` script for automatic porting is incomplete and imperfect.
 (Chances are it will require some manual cleanup afterwards.) The ``past``
-package also needs further work.
+package also needs to be expanded.
 
 
 Is the API stable?

docs/futurize.rst

@@ -1,7 +1,7 @@
 .. _forwards-conversion:
 
-Futurize: 2 to both
---------------------
+``futurize``: Py2 to Py2&3
+--------------------------
 
 .. include:: futurize_overview.rst
 
@@ -165,7 +165,7 @@ also reduce readability: see issue #58.)
 
 .. _forwards-conversion-stage2:
 
-Stage 2: Py3-style code with ``future`` wrappers for Py2
+Stage 2: Py3-style code with wrappers for Py2
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Run stage 2 of the conversion process with::

docs/pasteurize.rst

@@ -1,7 +1,7 @@
 .. _backwards-conversion:
 
-Pasteurize: 3 to both
----------------------
+``pasteurize``: Py3 to Py2&3
+----------------------------
 
 Running ``pasteurize -w mypy3module.py`` turns this Python 3 code::
     

docs/quickstart.rst

@@ -123,7 +123,7 @@ to be accessed under their Python 3 names and locations in Python 2::
     import xmlrpc.client
     import xmlrpc.server
 
-and others. For a complete list, see :ref:`list-standard-library-moves`.
+and others. For a complete list, see :ref:`list-standard-library-renamed`.
 
 .. _py2-dependencies:
 

docs/unicode_literals.rst

@@ -7,28 +7,22 @@ Should I import unicode_literals?
 The ``future`` package can be used with or without ``unicode_literals``
 imports.
 
-There is some contention in the community about whether it is advisable
-to import ``unicode_literals`` from ``__future__`` in a Python 2/3
-compatible codebase.
-
-In general, it is more compelling to use ``unicode_literals`` when back-porting
-new or existing Python 3 code to Python 2/3 than when porting existing Python 2
-code to 2/3. In the latter case, explicitly marking up all unicode string
-literals with ``u''`` prefixes would help to avoid unintentionally
-changing the existing Python 2 API.
-
-If changing the existing Python 2 API is not a concern, using
-``unicode_literals`` may speed up the porting process. If you use
-``unicode_literals``, testing and debugging your code with *Python 3* first is
-probably the easiest way to fix your code. After this, fixing Python 2 support
-will be easier.
-
-To avoid confusion, we recommend using ``unicode_literals`` everywhere
-across a code-base or not at all, instead of turning on for only some
-modules.
+There is some disagreement in the community about whether it is advisable to
+import ``unicode_literals`` from ``__future__`` in a Python 2/3 compatible
+codebase. In general, it is more compelling to use ``unicode_literals`` when
+back-porting new or existing Python 3 code to Python 2/3 than when porting
+existing Python 2 code to 2/3. In the latter case, explicitly marking up all
+unicode string literals with ``u''`` prefixes would help to avoid
+unintentionally changing the existing Python 2 API. If changing the existing
+Python 2 API is not a concern, using ``unicode_literals`` may speed up the
+porting process.
 
 This section summarizes the benefits and drawbacks of using
-``unicode_literals``.
+``unicode_literals``. To avoid confusion, we recommend using
+``unicode_literals`` everywhere across a code-base or not at all, instead of
+turning on for only some modules.
+
+
 
 Benefits
 ~~~~~~~~