The Python language has a substantial body of documentation, much of it contributed by various authors. The markup used for the Python documentation is reStructuredText, developed by the docutils project, amended by custom directives and using a toolset named Sphinx to post-process the HTML output.
If you’re interested in contributing to Python’s documentation, there’s no need to write reStructuredText if you’re not so inclined; plain text contributions are more than welcome as well. Send an e-mail to email@example.com or open an issue on the tracker.
Python’s documentation has long been considered to be good for a free programming language. There are a number of reasons for this, the most important being the early commitment of Python’s creator, Guido van Rossum, to providing documentation on the language and its libraries, and the continuing involvement of the user community in providing assistance for creating and maintaining documentation.
The involvement of the community takes many forms, from authoring to bug reports to just plain complaining when the documentation could be more complete or easier to use.
This section is aimed at authors and potential authors of documentation for Python. More specifically, it is for people contributing to the standard documentation and developing additional documents using the same tools as the standard documents. This guide will be less useful for authors using the Python documentation tools for topics other than Python, and less useful still for authors not using the tools at all.
If your interest is in contributing to the Python documentation, but you don’t have the time or inclination to learn reStructuredText and the markup structures documented here, there’s a welcoming place for you among the Python contributors as well. Any time you feel that you can clarify existing documentation or provide documentation that’s missing, the existing documentation team will gladly work with you to integrate your text, dealing with the markup for you. Please don’t let the material in this section stand between the documentation and your desire to help out!
Building the documentation#
To build the documentation, follow the steps in one of the sections below.
You can view the documentation after building the HTML
by opening the file
Doc/build/html/index.html in a web browser.
The following instructions all assume your current working dir is
Doc subdirectory in your CPython repository clone.
Make sure to switch to it with
cd Doc if necessary.
Create a virtual environment#
On Unix platforms that support make
(including Linux, macOS and BSD),
you can create a new
venv with the required dependencies using:
Building the docs with make will automatically use this environment without you having to activate it.
Build using make / make.bat#
make.bat batch file lacks a
make venv target.
Instead, it automatically installs any missing dependencies
into the currently activated environment (or the base Python, if none).
Make sure the environment you created above
is activated before running
To build the docs as HTML, run:
html to open the docs in a web browser
once the build completes.
To list other supported make targets, run:
Doc/README.rst for more information.
Build using Sphinx directly#
Advanced users may want to invoke Sphinx directly, to pass specialized options or to handle specific use cases.
python -m pip install --upgrade -r requirements.txt
Finally, directly invoke Sphinx with:
python -m sphinx -b html . build/html
To use a different Sphinx builder,
html above with the desired builder
Moved to Style guide.
Moved to Translating.