Merged revisions 82301 via svnmerge from
svn+ssh://svn.python.org/python/branches/py3k
................
r82301 | benjamin.peterson | 2010-06-28 00:32:30 +0200 (Mo, 28 Jun 2010) | 303 lines
Merged revisions 80605-80609,80642-80646,80651-80652,80674,80684-80686,80748,80852,80854,80870,80872-80873,80907,80915-80916,80951-80952,80976-80977,80985,81038-81040,81042,81053,81070,81104-81105,81114,81125,81245,81285,81402,81463,81516,81562-81563,81567,81593,81635,81680-81681,81684,81801,81888,81931-81933,81939-81942,81963,81984,81991,82120,82188,82264-82267 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r80605 | andrew.kuchling | 2010-04-28 19:22:16 -0500 (Wed, 28 Apr 2010) | 1 line
Add various items
........
r80606 | andrew.kuchling | 2010-04-28 20:44:30 -0500 (Wed, 28 Apr 2010) | 6 lines
Fix doubled 'the'.
Markup fixes to use :exc:, :option: in a few places.
(Glitch: unittest.main's -c ends up a link to the Python
interpreter's -c option. Should we skip using :option: for that
switch, or disable the auto-linking somehow?)
........
r80607 | andrew.kuchling | 2010-04-28 20:45:41 -0500 (Wed, 28 Apr 2010) | 1 line
Add various unittest items
........
r80608 | benjamin.peterson | 2010-04-28 22:18:05 -0500 (Wed, 28 Apr 2010) | 1 line
update pypy description
........
r80609 | benjamin.peterson | 2010-04-28 22:30:59 -0500 (Wed, 28 Apr 2010) | 1 line
update pypy url
........
r80642 | andrew.kuchling | 2010-04-29 19:49:09 -0500 (Thu, 29 Apr 2010) | 1 line
Always add space after RFC; reword paragraph
........
r80643 | andrew.kuchling | 2010-04-29 19:52:31 -0500 (Thu, 29 Apr 2010) | 6 lines
Reword paragraph to make its meaning clearer.
Antoine Pitrou: is my version of the paragraph still correct?
R. David Murray: is this more understandable than the previous version?
........
r80644 | andrew.kuchling | 2010-04-29 20:02:15 -0500 (Thu, 29 Apr 2010) | 1 line
Fix typos
........
r80645 | andrew.kuchling | 2010-04-29 20:32:47 -0500 (Thu, 29 Apr 2010) | 1 line
Markup fix; clarify by adding 'in that order'
........
r80646 | andrew.kuchling | 2010-04-29 20:33:40 -0500 (Thu, 29 Apr 2010) | 1 line
Add various items; rearrange unittest section a bit
........
r80651 | andrew.kuchling | 2010-04-30 08:46:55 -0500 (Fri, 30 Apr 2010) | 1 line
Minor grammar re-wording
........
r80652 | andrew.kuchling | 2010-04-30 08:47:34 -0500 (Fri, 30 Apr 2010) | 1 line
Add item
........
r80674 | andrew.kuchling | 2010-04-30 20:19:16 -0500 (Fri, 30 Apr 2010) | 1 line
Add various items
........
r80684 | andrew.kuchling | 2010-05-01 07:05:52 -0500 (Sat, 01 May 2010) | 1 line
Minor grammar fix
........
r80685 | andrew.kuchling | 2010-05-01 07:06:51 -0500 (Sat, 01 May 2010) | 1 line
Describe memoryview
........
r80686 | antoine.pitrou | 2010-05-01 07:16:39 -0500 (Sat, 01 May 2010) | 4 lines
Fix attribution. Travis didn't do much and he did a bad work.
(yes, this is a sensitive subject, sorry)
........
r80748 | andrew.kuchling | 2010-05-03 20:24:22 -0500 (Mon, 03 May 2010) | 1 line
Add some more items; the urlparse change is added twice
........
r80852 | andrew.kuchling | 2010-05-05 20:09:47 -0500 (Wed, 05 May 2010) | 1 line
Reword paragraph; fix filename, which should be pyconfig.h
........
r80854 | andrew.kuchling | 2010-05-05 20:10:56 -0500 (Wed, 05 May 2010) | 1 line
Add various items
........
r80870 | andrew.kuchling | 2010-05-06 09:14:09 -0500 (Thu, 06 May 2010) | 1 line
Describe ElementTree 1.3; rearrange new-module sections; describe dict views as sets; small edits and items
........
r80872 | andrew.kuchling | 2010-05-06 12:21:59 -0500 (Thu, 06 May 2010) | 1 line
Add 2 items; record ideas for two initial sections; clarify wording
........
r80873 | andrew.kuchling | 2010-05-06 12:27:57 -0500 (Thu, 06 May 2010) | 1 line
Change section title; point to unittest2
........
r80907 | andrew.kuchling | 2010-05-06 20:45:14 -0500 (Thu, 06 May 2010) | 1 line
Add a new section on the development plan; add an item
........
r80915 | antoine.pitrou | 2010-05-07 05:15:51 -0500 (Fri, 07 May 2010) | 3 lines
Fix some markup and a class name. Also, wrap a long line.
........
r80916 | andrew.kuchling | 2010-05-07 06:30:47 -0500 (Fri, 07 May 2010) | 1 line
Re-word text
........
r80951 | andrew.kuchling | 2010-05-07 20:15:26 -0500 (Fri, 07 May 2010) | 1 line
Add two items
........
r80952 | andrew.kuchling | 2010-05-07 20:35:55 -0500 (Fri, 07 May 2010) | 1 line
Get accents correct
........
r80976 | andrew.kuchling | 2010-05-08 08:28:03 -0500 (Sat, 08 May 2010) | 1 line
Add logging.dictConfig example; give up on writing a Ttk example
........
r80977 | andrew.kuchling | 2010-05-08 08:29:46 -0500 (Sat, 08 May 2010) | 1 line
Markup fixes
........
r80985 | andrew.kuchling | 2010-05-08 10:39:46 -0500 (Sat, 08 May 2010) | 7 lines
Write summary of the 2.7 release; rewrite the future section some more;
mention PYTHONWARNINGS env. var; tweak some examples for readability.
And with this commit, the "What's New" is done... except for a
complete read-through to polish the text, and fixing any reported errors,
but those tasks can easily wait until after beta2.
........
r81038 | benjamin.peterson | 2010-05-09 16:09:40 -0500 (Sun, 09 May 2010) | 1 line
finish clause
........
r81039 | andrew.kuchling | 2010-05-10 09:18:27 -0500 (Mon, 10 May 2010) | 1 line
Markup fix; re-word a sentence
........
r81040 | andrew.kuchling | 2010-05-10 09:20:12 -0500 (Mon, 10 May 2010) | 1 line
Use title case
........
r81042 | andrew.kuchling | 2010-05-10 10:03:35 -0500 (Mon, 10 May 2010) | 1 line
Link to unittest2 article
........
r81053 | florent.xicluna | 2010-05-10 14:59:22 -0500 (Mon, 10 May 2010) | 2 lines
Add a link on maketrans().
........
r81070 | andrew.kuchling | 2010-05-10 18:13:41 -0500 (Mon, 10 May 2010) | 1 line
Fix typo
........
r81104 | andrew.kuchling | 2010-05-11 19:38:44 -0500 (Tue, 11 May 2010) | 1 line
Revision pass: lots of edits, typo fixes, rearrangements
........
r81105 | andrew.kuchling | 2010-05-11 19:40:47 -0500 (Tue, 11 May 2010) | 1 line
Let's call this done
........
r81114 | andrew.kuchling | 2010-05-12 08:56:07 -0500 (Wed, 12 May 2010) | 1 line
Grammar fix
........
r81125 | andrew.kuchling | 2010-05-12 13:56:48 -0500 (Wed, 12 May 2010) | 1 line
#8696: add documentation for logging.config.dictConfig (PEP 391)
........
r81245 | andrew.kuchling | 2010-05-16 18:31:16 -0500 (Sun, 16 May 2010) | 1 line
Add cross-reference to later section
........
r81285 | vinay.sajip | 2010-05-18 03:16:27 -0500 (Tue, 18 May 2010) | 1 line
Fixed minor typo in ReST markup.
........
r81402 | vinay.sajip | 2010-05-21 12:41:34 -0500 (Fri, 21 May 2010) | 1 line
Updated logging documentation with more dictConfig information.
........
r81463 | georg.brandl | 2010-05-22 03:17:23 -0500 (Sat, 22 May 2010) | 1 line
#8785: less confusing description of regex.find*.
........
r81516 | andrew.kuchling | 2010-05-25 08:34:08 -0500 (Tue, 25 May 2010) | 1 line
Add three items
........
r81562 | andrew.kuchling | 2010-05-27 08:22:53 -0500 (Thu, 27 May 2010) | 1 line
Rewrite wxWidgets section
........
r81563 | andrew.kuchling | 2010-05-27 08:30:09 -0500 (Thu, 27 May 2010) | 1 line
Remove top-level 'General Questions' section, pushing up the questions it contains
........
r81567 | andrew.kuchling | 2010-05-27 16:29:59 -0500 (Thu, 27 May 2010) | 1 line
Add item
........
r81593 | georg.brandl | 2010-05-29 03:46:18 -0500 (Sat, 29 May 2010) | 1 line
#8616: add new turtle demo "nim".
........
r81635 | georg.brandl | 2010-06-01 02:25:23 -0500 (Tue, 01 Jun 2010) | 1 line
Put docs for RegexObject.search() before RegexObject.match() to mirror re.search() and re.match() order.
........
r81680 | vinay.sajip | 2010-06-03 17:34:42 -0500 (Thu, 03 Jun 2010) | 1 line
Issue #8890: Documentation changed to avoid reference to temporary files.
........
r81681 | sean.reifschneider | 2010-06-03 20:51:26 -0500 (Thu, 03 Jun 2010) | 2 lines
Issue8810: Clearing up docstring for tzinfo.utcoffset.
........
r81684 | vinay.sajip | 2010-06-04 08:41:02 -0500 (Fri, 04 Jun 2010) | 1 line
Issue #8890: Documentation changed to avoid reference to temporary files - other cases covered.
........
r81801 | andrew.kuchling | 2010-06-07 08:38:40 -0500 (Mon, 07 Jun 2010) | 1 line
#8875: Remove duplicated paragraph
........
r81888 | andrew.kuchling | 2010-06-10 20:54:58 -0500 (Thu, 10 Jun 2010) | 1 line
Add a few more items
........
r81931 | georg.brandl | 2010-06-12 01:26:54 -0500 (Sat, 12 Jun 2010) | 1 line
Fix punctuation.
........
r81932 | georg.brandl | 2010-06-12 01:28:58 -0500 (Sat, 12 Jun 2010) | 1 line
Document that an existing directory raises in mkdir().
........
r81933 | georg.brandl | 2010-06-12 01:45:33 -0500 (Sat, 12 Jun 2010) | 1 line
Update version in README.
........
r81939 | georg.brandl | 2010-06-12 04:45:01 -0500 (Sat, 12 Jun 2010) | 1 line
Use newer toctree syntax.
........
r81940 | georg.brandl | 2010-06-12 04:45:28 -0500 (Sat, 12 Jun 2010) | 1 line
Add document on how to build.
........
r81941 | georg.brandl | 2010-06-12 04:45:58 -0500 (Sat, 12 Jun 2010) | 1 line
Fix gratuitous indentation.
........
r81942 | georg.brandl | 2010-06-12 04:46:03 -0500 (Sat, 12 Jun 2010) | 1 line
Update README.
........
r81963 | andrew.kuchling | 2010-06-12 15:00:55 -0500 (Sat, 12 Jun 2010) | 1 line
Grammar fix
........
r81984 | georg.brandl | 2010-06-14 10:58:39 -0500 (Mon, 14 Jun 2010) | 1 line
#8993: fix reference.
........
r81991 | andrew.kuchling | 2010-06-14 19:38:58 -0500 (Mon, 14 Jun 2010) | 1 line
Add another bunch of items
........
r82120 | andrew.kuchling | 2010-06-20 16:45:45 -0500 (Sun, 20 Jun 2010) | 1 line
Note that Python 3.x isn't covered; add forward ref. for UTF-8; note error in 2.5 and up
........
r82188 | benjamin.peterson | 2010-06-23 19:02:46 -0500 (Wed, 23 Jun 2010) | 1 line
remove reverted changed
........
r82264 | georg.brandl | 2010-06-27 05:47:47 -0500 (Sun, 27 Jun 2010) | 1 line
Confusing punctuation.
........
r82265 | georg.brandl | 2010-06-27 05:49:23 -0500 (Sun, 27 Jun 2010) | 1 line
Use designated syntax for optional grammar element.
........
r82266 | georg.brandl | 2010-06-27 05:51:44 -0500 (Sun, 27 Jun 2010) | 1 line
Fix URL.
........
r82267 | georg.brandl | 2010-06-27 05:55:38 -0500 (Sun, 27 Jun 2010) | 1 line
Two typos.
........
................
diff --git a/Doc/documenting/building.rst b/Doc/documenting/building.rst
new file mode 100644
index 0000000..9ab2519
--- /dev/null
+++ b/Doc/documenting/building.rst
@@ -0,0 +1,91 @@
+Building the documentation
+==========================
+
+You need to have Python 2.4 or higher installed; the toolset used to build the
+docs is written in Python. It is called *Sphinx*, it is not included in this
+tree, but maintained separately. Also needed are the docutils, supplying the
+base markup that Sphinx uses, Jinja, a templating engine, and optionally
+Pygments, a code highlighter.
+
+
+Using make
+----------
+
+Luckily, a Makefile has been prepared so that on Unix, provided you have
+installed Python and Subversion, you can just run ::
+
+ make html
+
+to check out the necessary toolset in the `tools/` subdirectory and build the
+HTML output files. To view the generated HTML, point your favorite browser at
+the top-level index `build/html/index.html` after running "make".
+
+Available make targets are:
+
+ * "html", which builds standalone HTML files for offline viewing.
+
+ * "htmlhelp", which builds HTML files and a HTML Help project file usable to
+ convert them into a single Compiled HTML (.chm) file -- these are popular
+ under Microsoft Windows, but very handy on every platform.
+
+ To create the CHM file, you need to run the Microsoft HTML Help Workshop
+ over the generated project (.hhp) file.
+
+ * "latex", which builds LaTeX source files as input to "pdflatex" to produce
+ PDF documents.
+
+ * "text", which builds a plain text file for each source file.
+
+ * "linkcheck", which checks all external references to see whether they are
+ broken, redirected or malformed, and outputs this information to stdout
+ as well as a plain-text (.txt) file.
+
+ * "changes", which builds an overview over all versionadded/versionchanged/
+ deprecated items in the current version. This is meant as a help for the
+ writer of the "What's New" document.
+
+ * "coverage", which builds a coverage overview for standard library modules
+ and C API.
+
+ * "pydoc-topics", which builds a Python module containing a dictionary with
+ plain text documentation for the labels defined in
+ `tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and
+ keyword help.
+
+A "make update" updates the Subversion checkouts in `tools/`.
+
+
+Without make
+------------
+
+You'll need to install the Sphinx package, either by checking it out via ::
+
+ svn co http://svn.python.org/projects/external/Sphinx-0.6.5/sphinx tools/sphinx
+
+or by installing it from PyPI.
+
+Then, you need to install Docutils, either by checking it out via ::
+
+ svn co http://svn.python.org/projects/external/docutils-0.6/docutils tools/docutils
+
+or by installing it from http://docutils.sf.net/.
+
+You also need Jinja2, either by checking it out via ::
+
+ svn co http://svn.python.org/projects/external/Jinja-2.3.1/jinja2 tools/jinja2
+
+or by installing it from PyPI.
+
+You can optionally also install Pygments, either as a checkout via ::
+
+ svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments
+
+or from PyPI at http://pypi.python.org/pypi/Pygments.
+
+
+Then, make an output directory, e.g. under `build/`, and run ::
+
+ python tools/sphinx-build.py -b<builder> . build/<outputdirectory>
+
+where `<builder>` is one of html, text, latex, or htmlhelp (for explanations see
+the make targets above).
diff --git a/Doc/documenting/index.rst b/Doc/documenting/index.rst
index 88d97be..2c186a7 100644
--- a/Doc/documenting/index.rst
+++ b/Doc/documenting/index.rst
@@ -10,9 +10,9 @@
`reStructuredText`_, developed by the `docutils`_ project, amended by custom
directives and using a toolset named `Sphinx`_ to postprocess the HTML output.
-This document describes the style guide for our documentation, the custom
-reStructuredText markup introduced to support Python documentation and how it
-should be used, as well as the Sphinx build system.
+This document describes the style guide for our documentation as well as the
+custom reStructuredText markup introduced by Sphinx to support Python
+documentation and how it should be used.
.. _reStructuredText: http://docutils.sf.net/rst.html
.. _docutils: http://docutils.sf.net/
@@ -35,3 +35,4 @@
rest.rst
markup.rst
fromlatex.rst
+ building.rst
diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst
index eed51d2..6b54c5b 100644
--- a/Doc/documenting/markup.rst
+++ b/Doc/documenting/markup.rst
@@ -698,10 +698,10 @@
.. toctree::
:maxdepth: 2
- intro.rst
- strings.rst
- datatypes.rst
- numeric.rst
+ intro
+ strings
+ datatypes
+ numeric
(many more files listed here)
This accomplishes two things:
@@ -709,8 +709,8 @@
* Tables of contents from all those files are inserted, with a maximum depth
of two, that means one nested heading. ``toctree`` directives in those
files are also taken into account.
- * Sphinx knows that the relative order of the files ``intro.rst``,
- ``strings.rst`` and so forth, and it knows that they are children of the
+ * Sphinx knows that the relative order of the files ``intro``,
+ ``strings`` and so forth, and it knows that they are children of the
shown file, the library index. From this information it generates "next
chapter", "previous chapter" and "parent chapter" links.
diff --git a/Doc/documenting/style.rst b/Doc/documenting/style.rst
index 6145559..c3dded9 100644
--- a/Doc/documenting/style.rst
+++ b/Doc/documenting/style.rst
@@ -7,7 +7,7 @@
wherever possible. This particular style guide was selected mostly because it
seems reasonable and is easy to get online.
-Topics which are not covered in the Apple's style guide will be discussed in
+Topics which are not covered in Apple's style guide will be discussed in
this document.
All reST files use an indentation of 3 spaces. The maximum line length is 80