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* `python-docs-theme <https://pypi.org/project/python-docs-theme/>`_
24
25The easiest way to install these tools is to create a virtual environment and
26install the tools into there.
27
28Using make
29----------
30
31To get started on Unix, you can create a virtual environment and build
32documentation with the commands::
33
34 make venv
35 make html
36
37The virtual environment in the ``venv`` directory will contain all the tools
38necessary to build the documentation downloaded and installed from PyPI.
39If you'd like to create the virtual environment in a different location,
40you can specify it using the ``VENVDIR`` variable.
41
42You can also skip creating the virtual environment altogether, in which case
43the ``Makefile`` will look for instances of ``sphinx-build`` and ``blurb``
44installed on your process ``PATH`` (configurable with the ``SPHINXBUILD`` and
45``BLURB`` variables).
46
47On Windows, we try to emulate the ``Makefile`` as closely as possible with a
48``make.bat`` file. If you need to specify the Python interpreter to use,
49set the ``PYTHON`` environment variable.
50
51Available make targets are:
52
53* "clean", which removes all build files and the virtual environment.
54
55* "clean-venv", which removes the virtual environment directory.
56
57* "venv", which creates a virtual environment with all necessary tools
58 installed.
59
60* "html", which builds standalone HTML files for offline viewing.
61
62* "htmlview", which re-uses the "html" builder, but then opens the main page
63 in your default web browser.
64
65* "htmllive", which re-uses the "html" builder, rebuilds the docs,
66 starts a local server, and automatically reloads the page in your browser
67 when you make changes to reST files (Unix only).
68
69* "htmlhelp", which builds HTML files and a HTML Help project file usable to
70 convert them into a single Compiled HTML (.chm) file -- these are popular
71 under Microsoft Windows, but very handy on every platform.
72
73 To create the CHM file, you need to run the Microsoft HTML Help Workshop
74 over the generated project (.hhp) file. The ``make.bat`` script does this for
75 you on Windows.
76
77* "latex", which builds LaTeX source files as input to ``pdflatex`` to produce
78 PDF documents.
79
80* "text", which builds a plain text file for each source file.
81
82* "epub", which builds an EPUB document, suitable to be viewed on e-book
83 readers.
84
85* "linkcheck", which checks all external references to see whether they are
86 broken, redirected or malformed, and outputs this information to stdout as
87 well as a plain-text (.txt) file.
88
89* "changes", which builds an overview over all versionadded/versionchanged/
90 deprecated items in the current version. This is meant as a help for the
91 writer of the "What's New" document.
92
93* "coverage", which builds a coverage overview for standard library modules and
94 C API.
95
96* "pydoc-topics", which builds a Python module containing a dictionary with
97 plain text documentation for the labels defined in
98 ``tools/pyspecific.py`` -- pydoc needs these to show topic and keyword help.
99
100* "check", which checks for frequent markup errors.
101
102* "dist", (Unix only) which creates distributable archives of HTML, text,
103 PDF, and EPUB builds.
104
105
106Without make
107------------
108
109First, install the tool dependencies from PyPI.
110
111Then, from the ``Doc`` directory, run ::
112
113 sphinx-build -b<builder> . build/<builder>
114
115where ``<builder>`` is one of html, text, latex, or htmlhelp (for explanations
116see the make targets above).
117
118Deprecation header
119==================
120
121You can define the ``outdated`` variable in ``html_context`` to show a
122red banner on each page redirecting to the "latest" version.
123
124The link points to the same page on ``/3/``, sadly for the moment the
125language is lost during the process.
126
127
128Contributing
129============
130
131Bugs in the content should be reported to the
132`Python bug tracker <https://github.com/python/cpython/issues>`_.
133
134Bugs in the toolset should be reported to the tools themselves.
135
136To help with the documentation, or report any problems, please leave a message
137on `discuss.python.org <https://discuss.python.org/c/documentation>`_.
138