Clean up docs a bit

edschofield · edschofield · commit de89ea8f9ac6 · 2013-11-16T07:44:24.000+11:00
diff --git a/docs/_templates/navbar.html b/docs/_templates/navbar.html
@@ -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.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>
diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html
@@ -1,8 +1,8 @@
-<h3>Python-Future</h3>
-<p>
-  An easier, safer, cleaner upgrade path to Python 3.
-</p>
+<!--<h3>Python-Future</h3>
+<p>-->
+  Tools and help for an easier, safer, cleaner upgrade path to Python 3.
 <!--
+</p>
 <h3>Other Formats</h3>
 <p>
   You can download the documentation in other formats as well:
diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html
@@ -1,3 +1,3 @@
 <p class="logo"><a href="{{ pathto(master_doc) }}">
-  <img class="logo" src="{{ pathto('_static/python-future-logo.png', 1) }}" width="170" alt="Logo"/>
+  <img class="logo" src="{{ pathto('_static/python-future-logo.png', 1) }}" width="265" alt="Logo"/>
 </a></p>
diff --git a/docs/bytes_object.rst b/docs/bytes_object.rst
@@ -9,7 +9,7 @@ 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
+:mod:`future` contains a backport of the :mod:`bytes` object from Python 3
 which passes most of the Python 3 tests for :mod:`bytes`. (See
 ``future/tests/test_bytes.py`` in the source tree.) You can use it as
 follows::
@@ -86,7 +86,7 @@ and Py2 strings.
         FAILED (failures=31, errors=55, skipped=1)
         --------------------------------------------------------------
     
-    Using ``future``'s backported :class:`bytes` object passes most of
+    Using :mod:`future`'s backported :class:`bytes` object passes most of
     the same Python 3.3 tests on Py2, except those requiring specific
     wording in exception messages.
     
diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc
@@ -10,6 +10,7 @@ Contents:
    imports
    automatic_conversion
    porting
+   standard_library_incompatibilities
    faq
    changelog
    credits
diff --git a/docs/overview.rst b/docs/overview.rst
@@ -8,6 +8,8 @@ Overview
 codebase with minimal cruft and run it easily on Python 2 without further
 modification.
 
+``future`` comes with ``futurize``, a script that helps you to transition
+to supporting both Python 2 and 3 in a single codebase, module by module.
 
 .. _features:
 
@@ -20,10 +22,10 @@ Features
 -   300+ unit tests
 -   ``futurize`` script based on ``2to3``, ``3to2`` and parts of
     ``python-modernize`` for automatic conversion from either Py2 or Py3 to a
-    clean single-source codebase compatible with both Py3 and Py2
+    clean single-source codebase compatible with Python 2.6+ and Python 3.3+.
 -   a consistent set of utility functions and decorators selected from
-    Py2/3 compatibility interfaces from projects like six, IPython,
-    Jinja2, Django, and Pandas.
+    Py2/3 compatibility interfaces from projects like ``six``, ``IPython``,
+    ``Jinja2``, ``Django``, and ``Pandas``.
 
 
 .. _code-examples:
@@ -42,8 +44,8 @@ together with Python's built-in ``__future__`` module like this::
 followed by standard Python 3 code. The imports have no effect on Python
 3 but allow the code to run mostly unchanged on Python 3 and Python 2.6/2.7.
 
-For example, after these imports, this code runs identically on Python 3
-and 2.6/2.7::
+For example, this code behaves the same way on Python 2.6/2.7 after these
+imports as it normally does on Python 3::
     
     # Support for renamed standard library modules via import hooks
     from http.client import HttpConnection
@@ -61,13 +63,13 @@ and 2.6/2.7::
 
     # Backported Py3 str object
     s = str(u'ABCD')
-    assert s != b'ABCD'
+    assert s != bytes(b'ABCD')
     assert isinstance(s.encode('utf-8'), bytes)
     assert isinstance(b.decode('utf-8'), str)
     assert repr(s) == 'ABCD'      # consistent repr with Py3 (no u prefix)
     # These raise TypeErrors:
-    # b'B' in s
-    # s.find(b'A')
+    # bytes(b'B') in s
+    # s.find(bytes(b'A'))
 
     # Extra arguments for the open() function
     f = open('japanese.txt', encoding='utf-8', errors='replace')
diff --git a/docs/str_object.rst b/docs/str_object.rst
@@ -14,7 +14,7 @@ There are also other differences, such as the ``repr`` of unicode strings in
 Py2 having a ``u'...'`` prefix, versus simply ``'...'``, and the removal of
 the :func:`str.decode` method in Py3.
 
-``future`` contains a backport of the :mod:`str` object from Python 3 which
+:mod:`future` contains a backport of the :mod:`str` object from Python 3 which
 inherits from the Python 2 :class:`unicode` class but has customizations to
 improve compatibility with Python 3's :class:`str` object. You can use it as
 follows::
diff --git a/docs/what_else.rst b/docs/what_else.rst
@@ -3,15 +3,11 @@
 What else you need to know
 **************************
 
-``future`` cannot completely close the gap between Python 3 and Python 2
-with just the right :ref:`imports`. The following points require some
-additional work.
+The following points are important to know about when writing Python 2/3
+compatible code.
 
 .. _what-else-essentials:
 
-Essentials
-==========
-
 .. include:: bytes_object.rst
 .. include:: str_object.rst
 .. include:: int_object.rst
@@ -23,15 +19,8 @@ Essentials
 
 .. _what-else-advanced:
 
-Advanced
-========
-
 .. include:: bind_method.rst
 .. include:: metaclasses.rst
 
 ..
-    Standard library
-    ================
-
-.. include:: stdlib_incompatibilities.rst
 
