Update docs and improve their HTML layout

Author: edschofield

README.rst

@@ -7,11 +7,11 @@ Overview: Easy, clean, reliable Python 2/3 compatibility
 Python 3. It allows you to use a single, clean Python 3.x-compatible
 codebase to support both Python 2 and Python 3 with minimal overhead.
 
-It provides ``future`` and ``past`` packages with backports and forward ports of
-features from Python 3 and 2. It also comes with ``futurize`` and
-``pasteurize``, customized 2to3-based scripts that helps you to convert either
-Py2 or Py3 code easily to support both Python 2 and 3 in a single clean
-Py3-style codebase, module by module.
+It provides ``future`` and ``past`` packages with backports and forward
+ports of features from Python 3 and 2. It also comes with ``futurize`` and
+``pasteurize``, customized 2to3-based scripts that helps you to convert
+either Py2 or Py3 code easily to support both Python 2 and 3 in a single
+clean Py3-style codebase, module by module.
 
 Notable projects that use ``python-future`` for Python 3/2 compatibility
 are `Mezzanine <http://mezzanine.jupo.org/>`_ and `ObsPy
@@ -29,14 +29,18 @@ Features
     backports and remappings for 20 builtins with different semantics on Py3
     versus Py2
 
--   ``future.standard_library``, in conjunction with ``future.moves``, provides
-    support for importing standard library modules under their Python 3 names
+-   support for directly importing 30 standard library modules under
+    their Python 3 names on Py2
+
+-   support for importing the other 14 refactored standard library modules
+    under their Py3 names relatively cleanly via
+    ``future.standard_library`` and ``future.moves``
 
 -   ``past.builtins`` package provides forward-ports of 19 Python 2 types and
     builtin functions. These can aid with per-module code migrations.
 
 -   ``past.translation`` package supports transparent translation of Python 2
-    modules to Python 3 upon import. [This feature is currently in alpha.] 
+    modules to Python 3 upon import. [This feature is currently in alpha.]
 
 -   920+ unit tests, including many from the Py3.3 source tree.
 
@@ -153,7 +157,7 @@ interface works like this:
 Automatic conversion to Py2/3-compatible code
 ---------------------------------------------
 
-``future`` comes with two scripts called ``futurize`` and
+``python-future`` comes with two scripts called ``futurize`` and
 ``pasteurize`` to aid in making Python 2 code or Python 3 code compatible with
 both platforms (Py2&3). It is based on 2to3 and uses fixers from ``lib2to3``,
 ``lib3to2``, and ``python-modernize``, as well as custom fixers.
@@ -250,6 +254,7 @@ properly to a Python 2/3 compatible codebase using a tool like
 Note: the translation feature is still in alpha and needs more testing and
 development.
 
+For more info, see :ref:`translation`.
 
 Licensing
 ---------
@@ -269,7 +274,7 @@ Licensing
 Next steps
 ----------
 
-If you are new to ``python-future``, check out the `Quickstart Guide
+If you are new to Python-Future, check out the `Quickstart Guide
 <http://python-future.org/quickstart.html>`_.
 
 For an update on changes in the latest version, see the `What's New

docs/_static/python-future-icon-32.ico

@@ -12,7 +12,7 @@
           <span class="icon-bar"></span>
         </button>
 
-        <!--<a class="logo"> <img height="32" width="32" src="_static/python-future-logo.png" /></a>-->
+        <a class="logo"> <img height="32" width="32" src="_static/python-future-logo-textless-transparent.png" /></a>
         <a class="navbar-brand" href="{{ pathto(master_doc) }}">{% if theme_navbar_title -%}{{ theme_navbar_title|e }}{%- else -%}{{ project|e }}{%- endif -%}</a>
         <span class="navbar-text navbar-version pull-left"><b>{{ version|e }}</b></span>
       </div>

docs/_static/python-future-icon-white-32.ico

@@ -1,6 +1,7 @@
 <!--<h3>Python-Future</h3>
 <p>-->
   <h4>Easy, clean, reliable Python 2/3 compatibility</h4>
+  <a href="http://python-future.org">Table of Contents</a>
 <!--
 </p>
 <h3>Other Formats</h3>
@@ -12,8 +13,9 @@ <h3>Other Formats</h3>
   <li><a href="http://jinja.pocoo.org/docs/jinja-docs.zip">as zipped HTML</a>
 </ul>
 -->
-<!--<h3>Useful Links</h3>-->
+<!--<h3>Useful Links</h3>
 <ul>
   <li><a href="http://pypi.python.org/pypi/future">on PyPI</a></li>
   <li><a href="https://github.com/PythonCharmers/python-future">on GitHub</a></li>
 </ul>
+-->

docs/_static/python-future-logo-textless-transparent.png

@@ -3,18 +3,20 @@
 Changes in previous versions
 ****************************
 
+Changes in the most recent two versions are here: :ref:`whats-new`.
+
 .. _whats-new-0.12.4:
 
-What's new in version 0.12.4
-============================
+Changes in version 0.12.4
+=========================
 
 - Fix upcasting behaviour of newint (issue #76).
 
 
 .. _whats-new-0.12.3:
 
-What's new in version 0.12.3
-============================
+Changes in version 0.12.3
+=========================
 
 - Add "official Python 3.4 support": Py3.4 is now listed among the PyPI Trove
   classifiers and the tests now run successfully on Py3.4 (issue #67).
@@ -44,8 +46,8 @@ What's new in version 0.12.3
 
 .. _whats-new-0.12.2:
 
-What's new in version 0.12.2
-============================
+Changes in version 0.12.2
+=========================
 
 - Add ``bytes.maketrans()`` method (issue #51).
 - Add support for Python versions between 2.7.0 and 2.7.3 (inclusive)
@@ -55,8 +57,8 @@ What's new in version 0.12.2
 
 .. _whats-new-0.12.1:
 
-What's new in version 0.12.1
-============================
+Changes in version 0.12.1
+=========================
 
 - Python 2.6 support: ``future.standard_library`` now isolates the ``importlib``
   dependency to one function (``import_``) so the ``importlib`` backport may
@@ -67,8 +69,8 @@ What's new in version 0.12.1
 
 .. _whats-new-0.12:
 
-What's new in version 0.12.0
-============================
+Changes in version 0.12.0
+=========================
 
 The major new feature in this version is improvements in the support for the
 reorganized standard library (PEP 3108) and compatibility of the import
@@ -285,8 +287,8 @@ Many small improvements and fixes have been made across the project. Some highli
 
 .. _whats-new-0.11.4:
 
-What's new in version 0.11.4
-============================
+Changes in version 0.11.4
+=========================
 
 This release contains various small improvements and fixes:
 
@@ -312,8 +314,8 @@ This release contains various small improvements and fixes:
 
 .. _whats-new-0.11.3:
 
-What's new in version 0.11.3
-============================
+Changes in version 0.11.3
+=========================
 
 This release has improvements in the standard library import hooks mechanism and
 its compatibility with 3rd-party modules:
@@ -380,8 +382,8 @@ The ``pasteurize`` script for converting from Py3 to Py2/3 still adds
 
 .. _whats-new-0.11:
 
-What's new in version 0.11
-==========================
+Changes in version 0.11
+=======================
 
 There are several major new features in version 0.11. 
 
@@ -508,60 +510,11 @@ types but not their use.
 
 .. _whats-new-0.10.2:
 
-What's new in version 0.10.2
-============================
-
-
-.. Simpler imports
-.. ---------------
-.. 
-.. It is now possible to import builtins directly from the ``future``
-.. namespace as follows::
-.. 
-..     >>> from future import *
-..     
-.. or just those you need::
-.. 
-..     >>> from future import open, str
-
-
-Utility functions for raising exceptions with a traceback portably
-------------------------------------------------------------------
-
-The functions ``raise_with_traceback()`` and ``raise_`` were added to
-``future.utils`` to offer either the Python 3.x or Python 2.x behaviour
-for raising exceptions. Thanks to Joel Tratner for the contribution of
-these.
-
-
-.. _whats-new-0.10:
-
-What's new in version 0.10
-==========================
-
-Backported ``dict`` type
-------------------------
-
-``future.builtins`` now provides a Python 2 ``dict`` subclass whose
-:func:`keys`, :func:`values`, and :func:`items` methods produce
-memory-efficient iterators. On Python 2.7, these also have the same set-like
-view behaviour as on Python 3. This can streamline code needing to iterate
-over large dictionaries. For example::
-
-    from __future__ import print_function
-    from future.builtins import dict, range
-    
-    squares = dict({i: i**2 for i in range(10**7)})
-
-    assert not isinstance(d.items(), list)
-    # Because items() is memory-efficient, so is this:
-    square_roots = dict((i_squared, i) for (i, i_squared) in squares.items())
-
-For more information, see :ref:`dict-object`.
-
+Changes in version 0.10.2
+=========================
 
-Refactoring of standard_library hooks (v0.10.2)
------------------------------------------------
+New context-manager interface to standard_library hooks
+-------------------------------------------------------
 
 There is a new context manager ``future.standard_library.hooks``. Use it like
 this::
@@ -595,6 +548,31 @@ still available as aliases, but are deprecated.
 As usual, this feature has no effect on Python 3.
 
 
+.. _whats-new-0.10:
+
+Changes in version 0.10.0
+=========================
+
+Backported ``dict`` type
+------------------------
+
+``future.builtins`` now provides a Python 2 ``dict`` subclass whose
+:func:`keys`, :func:`values`, and :func:`items` methods produce
+memory-efficient iterators. On Python 2.7, these also have the same set-like
+view behaviour as on Python 3. This can streamline code needing to iterate
+over large dictionaries. For example::
+
+    from __future__ import print_function
+    from future.builtins import dict, range
+    
+    squares = dict({i: i**2 for i in range(10**7)})
+
+    assert not isinstance(d.items(), list)
+    # Because items() is memory-efficient, so is this:
+    square_roots = dict((i_squared, i) for (i, i_squared) in squares.items())
+
+For more information, see :ref:`dict-object`.
+
 
 Utility functions ``raise_`` and ``exec_``
 ------------------------------------------
@@ -617,12 +595,12 @@ Bugfixes
 
 .. _whats-new-0.9:
 
-What's new in version 0.9
-=========================
+Changes in version 0.9
+======================
 
 
-``isinstance`` checks supported natively with backported types
---------------------------------------------------------------
+``isinstance`` checks are supported natively with backported types
+------------------------------------------------------------------
 
 The ``isinstance`` function is no longer redefined in ``future.builtins``
 to operate with the backported ``int``, ``bytes`` and ``str``.
@@ -677,8 +655,8 @@ To work around this, ``future`` now provides a context manager called
 
 .. _whats-new-0.8:
 
-What's new in version 0.8
-=========================
+Changes in version 0.8.x
+========================
 
 Python 2.6 support
 ------------------
@@ -724,7 +702,21 @@ deprecated.
 .. _changelog:
 
 Summary of all changes
-======================
+**********************
+
+v0.14:
+  * New top-level ``builtins`` package on Py2 for cleaner imports. Equivalent to
+    ``future.builtins``
+  * New top-level packages on Py2 with the same names as Py3 standard modules:
+    ``configparser``, ``copyreg``, ``html``, ``http``, ``xmlrpc``, ``winreg``
+
+v0.13.1:
+  * Bug fixes
+
+v0.13.0:
+  * Cheat sheet for writing Python 2/3 compatible code
+  * ``to_int`` and ``from_int`` methods for ``newbytes``
+  * Bug fixes
 
 v0.12.0:
   * Add ``newobject`` and ``newlist`` types