Skip to content

Commit 16a14fa

Browse files
edschofieldedschofield
committed
More doc improvements
1 parent b4d4480 commit 16a14fa

14 files changed

Lines changed: 201 additions & 131 deletions

‎docs/source/automatic_conversion.rst‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -82,11 +82,16 @@ imports the renamed stdlib module under its Py3 name.
8282

8383
How well does ``futurize`` work?
8484
--------------------------------
85-
It is incomplete and makes mistakes, like 2to3, on which it is based.
8685

87-
``futurize`` is still useful to automate much of the boring repetitive
88-
text substitutions needed for the porting effort.
86+
It is still incomplete and makes mistakes, like 2to3, on which it is
87+
based.
8988

90-
Please report bugs on `GitHub <http://github.com/edschofield/python-future/>`_.
89+
Nevertheless, ``futurize`` is useful to automate much of the work
90+
of porting, particularly the boring repetitive text substitutions. It
91+
also helps to flag which parts of the code require attention.
9192

93+
Please report bugs on `GitHub
94+
<http://github.com/edschofield/python-future/>`_.
95+
96+
Contributions to ``futurize`` are particularly welcome! Please see :ref:`contributing`.
9297

‎docs/source/bind_method.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Binding a method to a class
66
Python 2 draws a distinction between bound and unbound methods, whereas
77
in Python 3 this distinction is gone: unbound methods have been removed
88
from the language. To bind a method to a class compatibly across Python
9-
3 and Python 2, you can use this helper function::
9+
3 and Python 2, you can use the :func:`bind_method` helper function::
1010

1111
from future.utils import bind_method
1212

‎docs/source/bytes_object.rst‎

Lines changed: 23 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ Python 2's :class:`str`, rather than a true implementation of the Python
1111

1212
``future`` contains a backport of the :mod:`bytes` object from Python 3
1313
which passes most of the Python 3 tests for :mod:`bytes`. (See
14-
:ref:`bytes-test-results`.) You can use it as follows::
14+
``future/tests/test_bytes.py`` in the source tree.) You can use it as
15+
follows::
1516

1617
from future.builtins import bytes
1718
@@ -56,25 +57,26 @@ code incompatibilities caused by the many differences between Py3 bytes
5657
and Py2 strings.
5758

5859

59-
.. _bytes-test-results:
60-
61-
Test results
62-
~~~~~~~~~~~~
63-
64-
For reference, when not using the backported :class:`bytes` object,
65-
running the Py3.3 ``bytes`` unit tests in ``test_bytes.py`` on Py2 (after
66-
fixing imports) gives this::
67-
68-
--------------------------------------------------------------
69-
Ran 203 tests in 0.209s
60+
..
61+
.. _bytes-test-results:
7062
71-
FAILED (failures=31, errors=55, skipped=1)
72-
--------------------------------------------------------------
73-
74-
The ``future`` backport of the Py3 :class:`bytes` object passes most of
75-
the Python 3 tests for ``bytes`` on Py2, except those requiring specific
76-
wording in exception messages.
77-
78-
See ``future/tests/test_bytes.py`` in the source for the unit tests that
79-
are actually run.
63+
bytes test results
64+
~~~~~~~~~~~~~~~~~~
65+
66+
For reference, when using Py2's default :class:`bytes` (i.e.
67+
:class:`str`), running the ``bytes`` unit tests from Python 3.3's
68+
``test_bytes.py`` on Py2 (after fixing imports) gives this::
69+
70+
--------------------------------------------------------------
71+
Ran 203 tests in 0.209s
72+
73+
FAILED (failures=31, errors=55, skipped=1)
74+
--------------------------------------------------------------
75+
76+
Using ``future``'s backported :class:`bytes` object passes most of
77+
the same Python 3.3 tests on Py2, except those requiring specific
78+
wording in exception messages.
79+
80+
See ``future/tests/test_bytes.py`` in the source for the actual set
81+
of unit tests that are actually run.
8082

‎docs/source/contents.rst.inc‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,19 @@
11
Contents:
2+
---------
23

34
.. toctree::
45
:maxdepth: 2
56

67
overview
78
quickstart
89
what_else
9-
future_imports
10+
imports
1011
automatic_conversion
1112
faq
1213
credits
1314

1415
Indices and tables
15-
==================
16+
------------------
1617

1718
* :ref:`genindex`
1819
* :ref:`modindex`

‎docs/source/credits.rst‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,23 @@
11
Credits
22
=======
3+
34
:Author: Ed Schofield
45
:Sponsor: Python Charmers Pty Ltd, Australia, and Python Charmers Pte
56
Ltd, Singapore. http://pythoncharmers.com
67
:Others: - The backported ``super()`` and ``range()`` functions are
7-
derived from Ryan Kelly's ``magicsuper`` module and Dan Crosta's
8-
``xrange`` module.
8+
derived from Ryan Kelly's ``magicsuper`` module and Dan
9+
Crosta's ``xrange`` module.
910
- The ``futurize`` script uses ``lib2to3``, ``lib3to2``, and
1011
parts of Armin Ronacher's ``python-modernize`` code.
11-
- The ``python_2_unicode_compatible`` decorator is from Django. The
12-
``implements_iterator`` and ``with_metaclass`` decorators are from
13-
Jinja2.
12+
- The ``python_2_unicode_compatible`` decorator is from
13+
Django. The ``implements_iterator`` and ``with_metaclass``
14+
decorators are from Jinja2.
1415
- ``future`` incorporates the ``six`` module by Benjamin
1516
Peterson as ``future.utils.six``.
17+
- Documentation is generated using ``sphinx`` using an
18+
adaptation of Armin Ronacher's stylesheets from Jinja2.
1619

20+
.. _licence:
1721

1822
Licensing
1923
---------

‎docs/source/custom_iterators.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@
33
Custom iterators
44
----------------
55

6-
If you define your own iterators, there is an incompatibility in the method name
7-
across Py3 and Py2. On Python 3 it is ``__next__``, whereas on Python 2 it is
8-
``next``.
6+
If you define your own iterators, there is an incompatibility in the
7+
method name across Py3 and Py2. On Python 3 it is ``__next__``, whereas
8+
on Python 2 it is ``next``.
99

1010
Use the following decorator to allow Py3-style iterators to work
1111
identically on Py2::

‎docs/source/custom_str_methods.rst‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@
33
Custom __str__ methods
44
----------------------
55

6-
If you define a custom ``__str__`` method for any of your classes, functions
7-
like ``print()`` expect ``__str__`` on Py2 to return a byte string, whereas on
8-
Py3 they expect a (unicode) string.
6+
If you define a custom ``__str__`` method for any of your classes,
7+
functions like ``print()`` expect ``__str__`` on Py2 to return a byte
8+
string, whereas on Py3 they expect a (unicode) string.
99

10-
Use the following decorator to map the ``__str__`` to ``__unicode__`` on Py2
11-
and define ``__str__`` to encode it as utf-8::
10+
Use the following decorator to map the ``__str__`` to ``__unicode__`` on
11+
Py2 and define ``__str__`` to encode it as utf-8::
1212

1313
from future.utils import python_2_unicode_compatible
1414

@@ -21,6 +21,7 @@ and define ``__str__`` to encode it as utf-8::
2121
# This then prints the Chinese characters for Confucius:
2222
print(a)
2323

24-
This decorator is identical to the decorator of the same name in ``django.utils.encoding``.
24+
This decorator is identical to the decorator of the same name in
25+
:mod:`django.utils.encoding`.
2526

2627
This decorator is a no-op on Python 3.

‎docs/source/dict_methods.rst‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
dictionary iterator methods
22
-----------------------------
33

4-
Python 3 dictionaries have ``.keys()``, ``.values()``, and ``.items()`` methods which
5-
return memory-efficient set-like objects, not lists. (See PEP 3106.)
4+
Python 3 dictionaries have ``.keys()``, ``.values()``, and ``.items()``
5+
methods which return memory-efficient set-like objects, not lists. (See
6+
`PEP 3106 <http://www.python.org/dev/peps/pep-3106/>`_.)
67

7-
If your dictionaries are small enough that the memory overhead of extra list
8-
creation is not significant, stick with standard Python 3 code in your Py3/2
9-
compatible codebase::
8+
If your dictionaries are small enough that the memory overhead of extra
9+
list creation is not significant, stick with standard Python 3 code in
10+
your Py3/2 compatible codebase::
1011

1112
for item in d:
1213
# code here
@@ -18,9 +19,9 @@ compatible codebase::
1819
# code here
1920

2021

21-
If your dictionaries are large, or if you want to use the Python 3 set-like
22-
behaviour on both Py3 and Python 2.7, then use the ``viewkeys`` etc. functions
23-
from ``future.utils``::
22+
If your dictionaries are large, or if you want to use the Python 3
23+
set-like behaviour on both Py3 and Python 2.7, then use the ``viewkeys``
24+
etc. functions from :mod:`future.utils`::
2425

2526
from future.utils import viewkeys, viewvalues, viewitems
2627

@@ -34,5 +35,3 @@ from ``future.utils``::
3435
# Set union:
3536
both = viewvalues(d1) | viewvalues(d2)
3637

37-
38-
[ref]: http://www.python.org/dev/peps/pep-3106/

0 commit comments

Comments
 (0)