blob: 50c199edab79dddaac91261aae2d26045cb4b7ab [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001Python Documentation README
2~~~~~~~~~~~~~~~~~~~~~~~~~~~
3
4This directory contains the reStructuredText (reST) sources to the Python
5documentation. You don't need to build them yourself, prebuilt versions are
6available at http://docs.python.org/download/.
7
8Documentation on the authoring Python documentation, including information about
9both style and markup, is available in the "Documenting Python" chapter of the
10documentation. There's also a chapter intended to point out differences to
11those familiar with the previous docs written in LaTeX.
12
13
14Building the docs
15=================
16
Benjamin Petersond7c3ed52010-06-27 22:32:30 +000017You need to have Python 2.4 or higher installed; the toolset used to build the
18docs is written in Python. It is called *Sphinx*, it is not included in this
19tree, but maintained separately. Also needed are the docutils, supplying the
20base markup that Sphinx uses, Jinja, a templating engine, and optionally
21Pygments, a code highlighter.
Georg Brandl116aa622007-08-15 14:28:22 +000022
23
24Using make
25----------
26
27Luckily, a Makefile has been prepared so that on Unix, provided you have
28installed Python and Subversion, you can just run ::
29
30 make html
31
32to check out the necessary toolset in the `tools/` subdirectory and build the
33HTML output files. To view the generated HTML, point your favorite browser at
34the top-level index `build/html/index.html` after running "make".
35
Georg Brandl716c3ac2007-08-30 18:34:23 +000036To use a Python interpreter that's not called ``python``, use the standard
37way to set Makefile variables, using e.g. ::
38
39 make html PYTHON=/usr/bin/python2.5
40
Georg Brandl116aa622007-08-15 14:28:22 +000041Available make targets are:
42
43 * "html", which builds standalone HTML files for offline viewing.
44
Georg Brandl116aa622007-08-15 14:28:22 +000045 * "htmlhelp", which builds HTML files and a HTML Help project file usable to
46 convert them into a single Compiled HTML (.chm) file -- these are popular
47 under Microsoft Windows, but very handy on every platform.
48
Benjamin Petersond7c3ed52010-06-27 22:32:30 +000049 To create the CHM file, you need to run the Microsoft HTML Help Workshop over
50 the generated project (.hhp) file.
Georg Brandl116aa622007-08-15 14:28:22 +000051
Benjamin Petersond7c3ed52010-06-27 22:32:30 +000052 * "latex", which builds LaTeX source files as input to "pdflatex" to produce
53 PDF documents.
Christian Heimes3feef612008-02-11 06:19:17 +000054
Georg Brandl0c77a822008-06-10 16:37:50 +000055 * "text", which builds a plain text file for each source file.
56
Georg Brandl183fe812011-01-05 11:00:25 +000057 * "epub", which builds an EPUB document, suitable to be viewed on e-book
58 readers.
59
Christian Heimes292d3512008-02-03 16:51:08 +000060 * "linkcheck", which checks all external references to see whether they are
Benjamin Petersond7c3ed52010-06-27 22:32:30 +000061 broken, redirected or malformed, and outputs this information to stdout as
62 well as a plain-text (.txt) file.
Christian Heimesd8654cf2007-12-02 15:22:16 +000063
Christian Heimes5b5e81c2007-12-31 16:14:33 +000064 * "changes", which builds an overview over all versionadded/versionchanged/
65 deprecated items in the current version. This is meant as a help for the
66 writer of the "What's New" document.
67
Benjamin Petersond7c3ed52010-06-27 22:32:30 +000068 * "coverage", which builds a coverage overview for standard library modules and
69 C API.
Christian Heimesd3eb5a152008-02-24 00:38:49 +000070
Benjamin Petersond7c3ed52010-06-27 22:32:30 +000071 * "pydoc-topics", which builds a Python module containing a dictionary with
72 plain text documentation for the labels defined in
73 `tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and
74 keyword help.
Georg Brandl6b38daa2008-06-01 21:05:17 +000075
Georg Brandl116aa622007-08-15 14:28:22 +000076A "make update" updates the Subversion checkouts in `tools/`.
77
78
79Without make
80------------
81
Georg Brandld94b4a72010-03-13 10:56:09 +000082You'll need to install the Sphinx package, either by checking it out via ::
Georg Brandl116aa622007-08-15 14:28:22 +000083
Georg Brandl6dc50f32011-01-15 16:45:03 +000084 svn co http://svn.python.org/projects/external/Sphinx-1.0.7/sphinx tools/sphinx
Georg Brandld94b4a72010-03-13 10:56:09 +000085
86or by installing it from PyPI.
Georg Brandl116aa622007-08-15 14:28:22 +000087
Benjamin Peterson92035012008-12-27 16:00:54 +000088Then, you need to install Docutils, either by checking it out via ::
Georg Brandl116aa622007-08-15 14:28:22 +000089
Georg Brandld94b4a72010-03-13 10:56:09 +000090 svn co http://svn.python.org/projects/external/docutils-0.6/docutils tools/docutils
Georg Brandl116aa622007-08-15 14:28:22 +000091
92or by installing it from http://docutils.sf.net/.
93
Georg Brandlb5b5bcc2009-04-27 16:29:51 +000094You also need Jinja2, either by checking it out via ::
95
Georg Brandld94b4a72010-03-13 10:56:09 +000096 svn co http://svn.python.org/projects/external/Jinja-2.3.1/jinja2 tools/jinja2
Georg Brandlb5b5bcc2009-04-27 16:29:51 +000097
98or by installing it from PyPI.
99
Benjamin Petersond7c3ed52010-06-27 22:32:30 +0000100You can optionally also install Pygments, either as a checkout via ::
Georg Brandl116aa622007-08-15 14:28:22 +0000101
Georg Brandld94b4a72010-03-13 10:56:09 +0000102 svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments
Georg Brandl116aa622007-08-15 14:28:22 +0000103
104or from PyPI at http://pypi.python.org/pypi/Pygments.
105
106
107Then, make an output directory, e.g. under `build/`, and run ::
108
109 python tools/sphinx-build.py -b<builder> . build/<outputdirectory>
110
Benjamin Peterson92035012008-12-27 16:00:54 +0000111where `<builder>` is one of html, text, latex, or htmlhelp (for explanations see
112the make targets above).
Georg Brandl116aa622007-08-15 14:28:22 +0000113
114
115Contributing
116============
117
Benjamin Peterson92035012008-12-27 16:00:54 +0000118Bugs in the content should be reported to the Python bug tracker at
119http://bugs.python.org.
Georg Brandl116aa622007-08-15 14:28:22 +0000120
Benjamin Peterson92035012008-12-27 16:00:54 +0000121Bugs in the toolset should be reported in the Sphinx bug tracker at
122http://www.bitbucket.org/birkenfeld/sphinx/issues/.
Georg Brandl116aa622007-08-15 14:28:22 +0000123
124You can also send a mail to the Python Documentation Team at docs@python.org,
125and we will process your request as soon as possible.
126
127If you want to help the Documentation Team, you are always welcome. Just send
128a mail to docs@python.org.
129
130
131Copyright notice
132================
133
134The Python source is copyrighted, but you can freely use and copy it
135as long as you don't change or remove the copyright notice:
136
137----------------------------------------------------------------------
Georg Brandled138532010-12-31 23:00:03 +0000138Copyright (c) 2000-2011 Python Software Foundation.
Georg Brandl116aa622007-08-15 14:28:22 +0000139All rights reserved.
140
141Copyright (c) 2000 BeOpen.com.
142All rights reserved.
143
144Copyright (c) 1995-2000 Corporation for National Research Initiatives.
145All rights reserved.
146
147Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
148All rights reserved.
149
150See the file "license.rst" for information on usage and redistribution
151of this file, and for a DISCLAIMER OF ALL WARRANTIES.
152----------------------------------------------------------------------