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 <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
10<https://devguide.python.org/documenting/>`_" chapter of the
11developers guide.
12
13
14Building the docs
15=================
16
17The documentation is built with several tools which are not included in this
18tree but are maintained separately and are available from
19`PyPI <https://pypi.org/>`_.
20
21* `Sphinx <https://pypi.org/project/Sphinx/>`_
22* `blurb <https://pypi.org/project/blurb/>`_
23
24The easiest way to install these tools is to create a virtual environment and
25install the tools into there.
26
27
28Using make
29----------
30
31To get started on UNIX, you can create a virtual environment with the command ::
32
33 make venv
34
35That will install all the tools necessary to build the documentation. Assuming
36the virtual environment was created in the ``venv`` directory (the default;
37configurable with the VENVDIR variable), you can run the following command to
38build the HTML output files::
39
40 make html
41
42By default, if the virtual environment is not created, the Makefile will
43look for instances of sphinxbuild and blurb installed on your process PATH
44(configurable with the SPHINXBUILD and BLURB variables).
45
46On Windows, we try to emulate the Makefile as closely as possible with a
47``make.bat`` file. If you need to specify the Python interpreter to use,
48set the PYTHON environment variable instead.
49
50Available make targets are:
51
52* "clean", which removes all build files.
53
54* "venv", which creates a virtual environment with all necessary tools
55 installed.
56
57* "html", which builds standalone HTML files for offline viewing.
58
59* "htmlview", which re-uses the "html" builder, but then opens the main page
60 in your default web browser.
61
62* "htmlhelp", which builds HTML files and a HTML Help project file usable to
63 convert them into a single Compiled HTML (.chm) file -- these are popular
64 under Microsoft Windows, but very handy on every platform.
65
66 To create the CHM file, you need to run the Microsoft HTML Help Workshop
67 over the generated project (.hhp) file. The make.bat script does this for
68 you on Windows.
69
70* "latex", which builds LaTeX source files as input to "pdflatex" to produce
71 PDF documents.
72
73* "text", which builds a plain text file for each source file.
74
75* "epub", which builds an EPUB document, suitable to be viewed on e-book
76 readers.
77
78* "linkcheck", which checks all external references to see whether they are
79 broken, redirected or malformed, and outputs this information to stdout as
80 well as a plain-text (.txt) file.
81
82* "changes", which builds an overview over all versionadded/versionchanged/
83 deprecated items in the current version. This is meant as a help for the
84 writer of the "What's New" document.
85
86* "coverage", which builds a coverage overview for standard library modules and
87 C API.
88
89* "pydoc-topics", which builds a Python module containing a dictionary with
90 plain text documentation for the labels defined in
91 `tools/pyspecific.py` -- pydoc needs these to show topic and keyword help.
92
93* "suspicious", which checks the parsed markup for text that looks like
94 malformed and thus unconverted reST.
95
96* "check", which checks for frequent markup errors.
97
98* "serve", which serves the build/html directory on port 8000.
99
100* "dist", (Unix only) which creates distributable archives of HTML, text,
101 PDF, and EPUB builds.
102
103
104Without make
105------------
106
107First, install the tool dependencies from PyPI.
108
109Then, from the ``Doc`` directory, run ::
110
111 sphinx-build -b<builder> . build/<builder>
112
113where ``<builder>`` is one of html, text, latex, or htmlhelp (for explanations
114see the make targets above).
115
116Deprecation header
117==================
118
119You can define the ``outdated`` variable in ``html_context`` to show a
120red banner on each page redirecting to the "latest" version.
121
122The link points to the same page on ``/3/``, sadly for the moment the
123language is lost during the process.
124
125
126Contributing
127============
128
129Bugs in the content should be reported to the
130`Python bug tracker <https://bugs.python.org>`_.
131
132Bugs in the toolset should be reported to the tools themselves.
133
134You can also send a mail to the Python Documentation Team at docs@python.org,
135and we will process your request as soon as possible.
136
137If you want to help the Documentation Team, you are always welcome. Just send
138a mail to docs@python.org.
139