blob: 457147df7c8c575b67cf6f05bb3910418496edd2 [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
Christian Heimes3feef612008-02-11 06:19:17 +000017You need to install Python 2.4 or higher (but Python 3.0 is not supported yet);
Georg Brandl716c3ac2007-08-30 18:34:23 +000018the toolset used to build the docs are written in Python. The toolset used
19to build the documentation is called *Sphinx*, it is not included in this
20tree, but maintained separately in the Python Subversion repository. Also
21needed are Jinja, a templating engine (included in Sphinx as a Subversion
22external), and optionally Pygments, a code highlighter.
Georg Brandl116aa622007-08-15 14:28:22 +000023
24
25Using make
26----------
27
28Luckily, a Makefile has been prepared so that on Unix, provided you have
29installed Python and Subversion, you can just run ::
30
31 make html
32
33to check out the necessary toolset in the `tools/` subdirectory and build the
34HTML output files. To view the generated HTML, point your favorite browser at
35the top-level index `build/html/index.html` after running "make".
36
Georg Brandl716c3ac2007-08-30 18:34:23 +000037To use a Python interpreter that's not called ``python``, use the standard
38way to set Makefile variables, using e.g. ::
39
40 make html PYTHON=/usr/bin/python2.5
41
Georg Brandl116aa622007-08-15 14:28:22 +000042Available make targets are:
43
44 * "html", which builds standalone HTML files for offline viewing.
45
46 * "web", which builds files usable with the Sphinx.web application (used to
47 serve the docs online at http://docs.python.org/).
48
49 * "htmlhelp", which builds HTML files and a HTML Help project file usable to
50 convert them into a single Compiled HTML (.chm) file -- these are popular
51 under Microsoft Windows, but very handy on every platform.
52
53 To create the CHM file, you need to run the Microsoft HTML Help Workshop
54 over the generated project (.hhp) file.
55
Christian Heimesd8654cf2007-12-02 15:22:16 +000056 * "latex", which builds LaTeX source files that can be run with "pdflatex"
57 to produce PDF documents.
Christian Heimes3feef612008-02-11 06:19:17 +000058
Christian Heimes292d3512008-02-03 16:51:08 +000059 * "linkcheck", which checks all external references to see whether they are
60 broken, redirected or malformed, and outputs this information to stdout
61 as well as a plain-text (.txt) file.
Christian Heimesd8654cf2007-12-02 15:22:16 +000062
Christian Heimes5b5e81c2007-12-31 16:14:33 +000063 * "changes", which builds an overview over all versionadded/versionchanged/
64 deprecated items in the current version. This is meant as a help for the
65 writer of the "What's New" document.
66
Christian Heimesd3eb5a152008-02-24 00:38:49 +000067 * "coverage", which builds a coverage overview for standard library modules
68 and C API.
69
Georg Brandl116aa622007-08-15 14:28:22 +000070A "make update" updates the Subversion checkouts in `tools/`.
71
72
73Without make
74------------
75
76You'll need to checkout the Sphinx package to the `tools/` directory::
77
78 svn co http://svn.python.org/projects/doctools/trunk/sphinx tools/sphinx
79
80Then, you need to install Docutils 0.4 (the SVN snapshot won't work), either
81by checking it out via ::
82
83 svn co http://svn.python.org/projects/external/docutils-0.4/docutils tools/docutils
84
85or by installing it from http://docutils.sf.net/.
86
87You can optionally also install Pygments, either as a checkout via ::
88
Georg Brandl9afde1c2007-11-01 20:32:30 +000089 svn co http://svn.python.org/projects/external/Pygments-0.9/pygments tools/pygments
Georg Brandl116aa622007-08-15 14:28:22 +000090
91or from PyPI at http://pypi.python.org/pypi/Pygments.
92
93
94Then, make an output directory, e.g. under `build/`, and run ::
95
96 python tools/sphinx-build.py -b<builder> . build/<outputdirectory>
97
98where `<builder>` is one of html, web or htmlhelp (for explanations see the make
99targets above).
100
101
102Contributing
103============
104
105For bugs in the content, the online version at http://docs.python.org/ has a
106"suggest change" facility that can be used to correct errors in the source text
107and submit them as a patch to the maintainers.
108
109Bugs in the toolset should be reported in the Python bug tracker at
110http://bugs.python.org/.
111
112You can also send a mail to the Python Documentation Team at docs@python.org,
113and we will process your request as soon as possible.
114
115If you want to help the Documentation Team, you are always welcome. Just send
116a mail to docs@python.org.
117
118
119Copyright notice
120================
121
122The Python source is copyrighted, but you can freely use and copy it
123as long as you don't change or remove the copyright notice:
124
125----------------------------------------------------------------------
Barry Warsaw659fc422008-03-01 17:45:23 +0000126Copyright (c) 2000-2008 Python Software Foundation.
Georg Brandl116aa622007-08-15 14:28:22 +0000127All rights reserved.
128
129Copyright (c) 2000 BeOpen.com.
130All rights reserved.
131
132Copyright (c) 1995-2000 Corporation for National Research Initiatives.
133All rights reserved.
134
135Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
136All rights reserved.
137
138See the file "license.rst" for information on usage and redistribution
139of this file, and for a DISCLAIMER OF ALL WARRANTIES.
140----------------------------------------------------------------------