README.txt
1Python 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 <https://docs.python.org/dev/download.html>.
7
8Documentation on authoring Python documentation, including information about
9both style and markup, is available in the "Documenting Python" chapter of the
10developers guide <https://docs.python.org/devguide/documenting.html>.
11
12
13Building the docs
14=================
15
16You need to have Sphinx <http://sphinx-doc.org/> installed; it is the toolset
17used to build the docs. It is not included in this tree, but maintained
18separately and available from PyPI <https://pypi.python.org/pypi/Sphinx>.
19
20
21Using make
22----------
23
24A Makefile has been prepared so that on Unix, provided you have installed
25Sphinx, you can just run ::
26
27 make html
28
29to build the HTML output files.
30
31On Windows, we try to emulate the Makefile as closely as possible with a
32``make.bat`` file.
33
34To use a Python interpreter that's not called ``python``, use the standard
35way to set Makefile variables, using e.g. ::
36
37 make html PYTHON=python3
38
39On Windows, set the PYTHON environment variable instead.
40
41To use a specific sphinx-build (something other than ``sphinx-build``), set
42the SPHINXBUILD variable.
43
44Available make targets are:
45
46* "clean", which removes all build files.
47
48* "html", which builds standalone HTML files for offline viewing.
49
50* "htmlview", which re-uses the "html" builder, but then opens the main page
51 in your default web browser.
52
53* "htmlhelp", which builds HTML files and a HTML Help project file usable to
54 convert them into a single Compiled HTML (.chm) file -- these are popular
55 under Microsoft Windows, but very handy on every platform.
56
57 To create the CHM file, you need to run the Microsoft HTML Help Workshop
58 over the generated project (.hhp) file. The make.bat script does this for
59 you on Windows.
60
61* "latex", which builds LaTeX source files as input to "pdflatex" to produce
62 PDF documents.
63
64* "text", which builds a plain text file for each source file.
65
66* "epub", which builds an EPUB document, suitable to be viewed on e-book
67 readers.
68
69* "linkcheck", which checks all external references to see whether they are
70 broken, redirected or malformed, and outputs this information to stdout as
71 well as a plain-text (.txt) file.
72
73* "changes", which builds an overview over all versionadded/versionchanged/
74 deprecated items in the current version. This is meant as a help for the
75 writer of the "What's New" document.
76
77* "coverage", which builds a coverage overview for standard library modules and
78 C API.
79
80* "pydoc-topics", which builds a Python module containing a dictionary with
81 plain text documentation for the labels defined in
82 `tools/pyspecific.py` -- pydoc needs these to show topic and keyword help.
83
84* "suspicious", which checks the parsed markup for text that looks like
85 malformed and thus unconverted reST.
86
87* "check", which checks for frequent markup errors.
88
89* "serve", which serves the build/html directory on port 8000.
90
91* "dist", (Unix only) which creates distributable archives of HTML, text,
92 PDF, and EPUB builds.
93
94
95Without make
96------------
97
98Install the Sphinx package and its dependencies from PyPI.
99
100Then, from the ``Doc`` directory, run ::
101
102 sphinx-build -b<builder> . build/<builder>
103
104where ``<builder>`` is one of html, text, latex, or htmlhelp (for explanations
105see the make targets above).
106
107
108Contributing
109============
110
111Bugs in the content should be reported to the Python bug tracker at
112https://bugs.python.org.
113
114Bugs in the toolset should be reported in the Sphinx bug tracker at
115https://www.bitbucket.org/birkenfeld/sphinx/issues/.
116
117You can also send a mail to the Python Documentation Team at docs@python.org,
118and we will process your request as soon as possible.
119
120If you want to help the Documentation Team, you are always welcome. Just send
121a mail to docs@python.org.
122