8000 More doc updates · thecodingchicken/python-future@ff8a39c · GitHub
[go: up one dir, main page]
Skip to content

Commit ff8a39c

Browse files
edschofieldedschofield
committed
More doc updates
1 parent a92d231 commit ff8a39c

File tree

9 files changed

+37
-40
lines changed

9 files changed

+37
-40
lines changed

‎docs/automatic_conversion.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. _automatic-conversion:
22

3-
Automatic conversion to Py2/3 with ``futurize`` and ``pasteurize``
4-
==================================================================
3+
Automatic conversion to Py2&3
4+
=============================
55

66
The ``future`` source tree includes scripts called ``futurize`` and
77
``pasteurize`` to aid in making Python 2 code or Python 3 code compatible with

‎docs/conf.py

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@
110110
#'navbar_title': "Python-Future",
111111

112112
# Tab name for entire site. (Default: "Site")
113-
'navbar_site_name': "All pages",
113+
'navbar_site_name': "Contents",
114114

115115
# A list of tuples containing pages or urls to link to.
116116
# Valid tuples should be in the following forms:
121121
# an arbitrary url.
122122
'navbar_links': [
123123
("Overview", "overview"),
124+
("Cheat Sheet", "compatible_idioms.html", True),
124125
("FAQ", "faq.html", True),
125126
# ("Link", "http://example.com", True),
126127
],
127128

128129
# Render the next and previous page links in navbar. (Default: true)
129-
'navbar_sidebarrel': True,
130+
'navbar_sidebarrel': False,
130131

131132
# Render the current pages TOC in the navbar. (Default: true)
132133
'navbar_pagenav': True,
133134

134135
# Global TOC depth for "site" navbar tab. (Default: 1)
135136
# Switching to -1 shows all levels.
136-
'globaltoc_depth': 2,
137+
'globaltoc_depth': 3,
137138

138139
# Include hidden TOCs in Site navbar?
139140
#
@@ -224,10 +225,10 @@
224225
#html_split_index = False
225226

226227
# If true, links to the reST sources are added to the pages.
227-
#html_show_sourcelink = True
228+
html_show_sourcelink = False
228229

229230
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
230-
#html_show_sphinx = True
231+
html_show_sphinx = False
231232

232233
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
233234
#html_show_copyright = True

‎docs/contents.rst.inc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@ Contents:
44
.. toctree::
55
:maxdepth: 2
66

7-
overview
87
whatsnew
8+
overview
99
quickstart
1010
compatible_idioms
1111
imports

‎docs/credits.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ Patches
5555
- Nicolas Delaby
5656
- Corey Farwell
5757
- Eric Firing
58+
- Alexey Kotlyarov
5859
- Lion Krischer
5960
- Marcin Kuzminski
6061
- Joshua Landau
@@ -66,6 +67,7 @@ Patches
6667
- Jeff Tratner
6768
- Mystic-Mirage (GitHub)
6869
- str4d (GitHub)
70+
- 9seconds (GitHub)
6971

7072
Suggestions and Feedback
7173
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -94,8 +96,8 @@ Other Credits
9496
- The ``raise_`` and ``raise_with_traceback`` functions were contributed by
9597
Jeff Tratner.
9698

97-
- Documentation is generated with ``sphinx`` using the ``sphinx-bootstrap``
98-
theme.
99+
- Documentation is generated with `Sphinx <http://sphinx.pocoo.org>`_ using the
100+
``sphinx-bootstrap`` theme.
99101

100102
- ``past.translation`` is inspired by and borrows some code from Sanjay Vinip's
101103
``uprefix`` module.

‎docs/faq.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ Python 3.x is a better language and better set of standard libraries than
2828
Python 2.x in many ways. Python 3.x is cleaner, less warty, and easier to
2929
learn than Python 2. It has better memory efficiency, easier Unicode handling,
3030
and powerful new features like the `asyncio
31-
<https://pypi.python.org/pypi/asyncio>`_ module.
31+
<https://docs.python.org/3/library/asyncio.html>`_ module.
3232

3333
.. Unicode handling is also much easier. For example, see `this page
3434
.. <http://pythonhosted.org/kitchen/unicode-frustrations.html>`_
@@ -115,8 +115,8 @@ community to remain united around a single version of the language.
115115
Maturity
116116
========
117117

118-
Is it tested?
119-
-------------
118+
How well has it been tested?
119+
----------------------------
120120

121121
``future`` is used by several major projects, including `mezzanine
122122
<http://mezzanine.jupo.org>`_ and `ObsPy <http://www.obspy.org>`_. It is also
@@ -129,7 +129,7 @@ from the Python 3.3 test suite.
129129
In general, the ``future`` package itself is in good shape, whereas the
130130
``futurize`` script for automatic porting is incomplete and imperfect.
131131
(Chances are it will require some manual cleanup afterwards.) The ``past``
132-
package also needs further work.
132+
package also needs to be expanded.
133133

134134

135135
Is the API stable?

‎docs/futurize.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. _forwards-conversion:
22

3-
Futurize: 2 to both
4-
--------------------
3+
``futurize``: Py2 to Py2&3
4+
--------------------------
55

66
.. include:: futurize_overview.rst
77

@@ -165,7 +165,7 @@ also reduce readability: see issue #58.)
165165

166166
.. _forwards-conversion-stage2:
167167

168-
Stage 2: Py3-style code with ``future`` wrappers for Py2
168+
Stage 2: Py3-style code with wrappers for Py2
169169
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
170170

171171
Run stage 2 of the conversion process with::

‎docs/pasteurize.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. _backwards-conversion:
22

3-
Pasteurize: 3 to both
4-
---------------------
3+
``pasteurize``: Py3 to Py2&3
4+
----------------------------
55

66
Running ``pasteurize -w mypy3module.py`` turns this Python 3 code::
77

‎docs/quickstart.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ to be accessed under their Python 3 names and locations in Python 2::
123123
import xmlrpc.client
124124
import xmlrpc.server
125125

126-
and others. For a complete list, see :ref:`list-standard-library-moves`.
126+
and others. For a complete list, see :ref:`list-standard-library-renamed`.
127127

128128
.. _py2-dependencies:
129129

‎docs/unicode_literals.rst

Lines changed: 14 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -7,28 +7,22 @@ Should I import unicode_literals?
77
The ``future`` package can be used with or without ``unicode_literals``
88
imports.
99

10-
There is some contention in the community about whether it is advisable
11-
to import ``unicode_literals`` from ``__future__`` in a Python 2/3
12-
compatible codebase.
13-
14-
In general, it is more compelling to use ``unicode_literals`` when back-porting
15-
new or existing Python 3 code to Python 2/3 than when porting existing Python 2
16-
code to 2/3. In the latter case, explicitly marking up all unicode string
17-
literals with ``u''`` prefixes would help to avoid unintentionally
18-
changing the existing Python 2 API.
19-
20-
If changing the existing Python 2 API is not a concern, using
21-
``unicode_literals`` may speed up the porting process. If you use
22-
``unicode_literals``, testing and debugging your code with *Python 3* first is
23-
probably the easiest way to fix your code. After this, fixing Python 2 support
24-
will be easier.
25-
26-
To avoid confusion, we recommend using ``unicode_literals`` everywhere
27-
across a code-base or not at all, instead of turning on for only some
28-
modules.
10+
There is some disagreement in the community about whether it is advisable to
11+
import ``unicode_literals`` from ``__future__`` in a Python 2/3 compatible
12+
codebase. In general, it is more compelling to use ``unicode_literals`` when
13+
back-porting new or existing Python 3 code to Python 2/3 than when porting
14+
existing Python 2 code to 2/3. In the latter case, explicitly marking up all
15+
unicode string literals with ``u''`` prefixes would help to avoid
16+
unintentionally changing the existing Python 2 API. If changing the existing
17+
Python 2 API is not a concern, using ``unicode_literals`` may speed up the
18+
porting process.
2919

3020
This section summarizes the benefits and drawbacks of using
31-
``unicode_literals``.
21+
``unicode_literals``. To avoid confusion, we recommend using
22+
``unicode_literals`` everywhere across a code-base or not at all, instead of
23+
turning on for only some modules.
24+
25+
3226

3327
Benefits
3428
~~~~~~~~

0 commit comments

Comments
 (0)
0