blob: b34916040eb93fa4161e555ba1a1ef0b9a39c1ad [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
Rogerb3f1f592017-02-15 17:54:05 -05005documentation. You don't need to build them yourself, `prebuilt versions are
6available <https://docs.python.org/dev/download.html>`_.
Georg Brandl116aa622007-08-15 14:28:22 +00007
Zachary Ware1de519c2014-04-29 09:26:56 -05008Documentation on authoring Python documentation, including information about
Rogerb3f1f592017-02-15 17:54:05 -05009both style and markup, is available in the "`Documenting Python
Lisa Hewus Fresh384899d2017-08-30 09:37:43 -070010<https://devguide.python.org/documenting/>`_" chapter of the
Rogerb3f1f592017-02-15 17:54:05 -050011developers guide.
Georg Brandl116aa622007-08-15 14:28:22 +000012
13
14Building the docs
15=================
16
Ned Deily590665c2017-09-07 17:17:53 -070017The 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/>`_
Jon Wayne Parrottbf63e8d2018-03-01 13:02:50 -080023* `python-docs-theme <https://pypi.org/project/python-docs-theme/>`_
Ned Deily590665c2017-09-07 17:17:53 -070024
Ned Deily122fc132017-11-27 17:07:32 -050025The easiest way to install these tools is to create a virtual environment and
26install the tools into there.
Georg Brandl116aa622007-08-15 14:28:22 +000027
Georg Brandl116aa622007-08-15 14:28:22 +000028Using make
29----------
30
Ned Deily122fc132017-11-27 17:07:32 -050031To 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 ``env`` directory (the default;
37configurable with the VENVDIR variable), you can run the following command to
38build the HTML output files::
Ned Deily590665c2017-09-07 17:17:53 -070039
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).
Georg Brandl116aa622007-08-15 14:28:22 +000045
Georg Brandl18a364f2014-03-10 19:26:57 +010046On Windows, we try to emulate the Makefile as closely as possible with a
Ned Deily122fc132017-11-27 17:07:32 -050047``make.bat`` file. If you need to specify the Python interpreter to use,
48set the PYTHON environment variable instead.
Georg Brandl716c3ac2007-08-30 18:34:23 +000049
Georg Brandl116aa622007-08-15 14:28:22 +000050Available make targets are:
51
Georg Brandl69a72032014-10-29 08:18:43 +010052* "clean", which removes all build files.
Zachary Ware1de519c2014-04-29 09:26:56 -050053
Ned Deily590665c2017-09-07 17:17:53 -070054* "venv", which creates a virtual environment with all necessary tools
55 installed.
56
Georg Brandl69a72032014-10-29 08:18:43 +010057* "html", which builds standalone HTML files for offline viewing.
Georg Brandl116aa622007-08-15 14:28:22 +000058
Georg Brandl69a72032014-10-29 08:18:43 +010059* "htmlview", which re-uses the "html" builder, but then opens the main page
60 in your default web browser.
Zachary Ware1de519c2014-04-29 09:26:56 -050061
Georg Brandl69a72032014-10-29 08:18:43 +010062* "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.
Georg Brandl116aa622007-08-15 14:28:22 +000065
Georg Brandl69a72032014-10-29 08:18:43 +010066 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.
Georg Brandl116aa622007-08-15 14:28:22 +000069
Georg Brandl69a72032014-10-29 08:18:43 +010070* "latex", which builds LaTeX source files as input to "pdflatex" to produce
71 PDF documents.
Christian Heimes3feef612008-02-11 06:19:17 +000072
Georg Brandl69a72032014-10-29 08:18:43 +010073* "text", which builds a plain text file for each source file.
Georg Brandl0c77a822008-06-10 16:37:50 +000074
Georg Brandl69a72032014-10-29 08:18:43 +010075* "epub", which builds an EPUB document, suitable to be viewed on e-book
76 readers.
Georg Brandl183fe812011-01-05 11:00:25 +000077
Georg Brandl69a72032014-10-29 08:18:43 +010078* "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.
Christian Heimesd8654cf2007-12-02 15:22:16 +000081
Georg Brandl69a72032014-10-29 08:18:43 +010082* "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.
Christian Heimes5b5e81c2007-12-31 16:14:33 +000085
Georg Brandl69a72032014-10-29 08:18:43 +010086* "coverage", which builds a coverage overview for standard library modules and
87 C API.
Christian Heimesd3eb5a152008-02-24 00:38:49 +000088
Georg Brandl69a72032014-10-29 08:18:43 +010089* "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.
Georg Brandl6b38daa2008-06-01 21:05:17 +000092
Georg Brandl69a72032014-10-29 08:18:43 +010093* "suspicious", which checks the parsed markup for text that looks like
94 malformed and thus unconverted reST.
Georg Brandl116aa622007-08-15 14:28:22 +000095
Georg Brandl69a72032014-10-29 08:18:43 +010096* "check", which checks for frequent markup errors.
Zachary Ware1de519c2014-04-29 09:26:56 -050097
Georg Brandl69a72032014-10-29 08:18:43 +010098* "serve", which serves the build/html directory on port 8000.
Zachary Ware1de519c2014-04-29 09:26:56 -050099
Georg Brandl69a72032014-10-29 08:18:43 +0100100* "dist", (Unix only) which creates distributable archives of HTML, text,
101 PDF, and EPUB builds.
Zachary Ware1de519c2014-04-29 09:26:56 -0500102
Georg Brandl116aa622007-08-15 14:28:22 +0000103
104Without make
105------------
106
Ned Deily122fc132017-11-27 17:07:32 -0500107First, install the tool dependencies from PyPI.
Georg Brandl116aa622007-08-15 14:28:22 +0000108
Ned Deily122fc132017-11-27 17:07:32 -0500109Then, from the ``Doc`` directory, run ::
110
111 sphinx-build -b<builder> . build/<builder>
Georg Brandl116aa622007-08-15 14:28:22 +0000112
Georg Brandl18a364f2014-03-10 19:26:57 +0100113where ``<builder>`` is one of html, text, latex, or htmlhelp (for explanations
114see the make targets above).
Georg Brandl116aa622007-08-15 14:28:22 +0000115
116
117Contributing
118============
119
Lisa Hewus Fresh384899d2017-08-30 09:37:43 -0700120Bugs in the content should be reported to the
Rogerb3f1f592017-02-15 17:54:05 -0500121`Python bug tracker <https://bugs.python.org>`_.
Georg Brandl116aa622007-08-15 14:28:22 +0000122
Ned Deily590665c2017-09-07 17:17:53 -0700123Bugs in the toolset should be reported to the tools themselves.
Georg Brandl116aa622007-08-15 14:28:22 +0000124
125You can also send a mail to the Python Documentation Team at docs@python.org,
126and we will process your request as soon as possible.
127
128If you want to help the Documentation Team, you are always welcome. Just send
129a mail to docs@python.org.