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. ........ ................
author: Georg Brandl <georg@python.org> 2010-07-11 10:41:07 (GMT)
committer: Georg Brandl <georg@python.org> 2010-07-11 10:41:07 (GMT)
commit: c62efa87f68af07f3a9511984e0055a746514c9d (patch)
tree: 0e13361c7f3bf99848dc9e26aff6e9f7fb80d269 /Doc/documenting
parent: 725443fef975a6de661b38c358c33c08e22caec5 (diff)
download: cpython-c62efa87f68af07f3a9511984e0055a746514c9d.zip
cpython-c62efa87f68af07f3a9511984e0055a746514c9d.tar.gz
cpython-c62efa87f68af07f3a9511984e0055a746514c9d.tar.bz2
4 files changed, 102 insertions, 10 deletions
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 @@ contributed by various authors. The markup used for the Python documentation is
 `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 @@ should be used, as well as the Sphinx build system.
    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 @@ tables of contents.  The ``toctree`` directive is the central element.
       .. 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.  The ``toctree`` directive is the central element.
    * 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 @@ The Python documentation should follow the `Apple Publications Style Guide`_
 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
author	Georg Brandl <georg@python.org>	2010-07-11 10:41:07 (GMT)
committer	Georg Brandl <georg@python.org>	2010-07-11 10:41:07 (GMT)
commit	c62efa87f68af07f3a9511984e0055a746514c9d (patch)
tree	0e13361c7f3bf99848dc9e26aff6e9f7fb80d269 /Doc/documenting
parent	725443fef975a6de661b38c358c33c08e22caec5 (diff)
download	cpython-c62efa87f68af07f3a9511984e0055a746514c9d.zip cpython-c62efa87f68af07f3a9511984e0055a746514c9d.tar.gz cpython-c62efa87f68af07f3a9511984e0055a746514c9d.tar.bz2