- Getting started
- Development workflow
- Issues and triaging
- Documentation
- Testing and buildbots
- Development tools
- Core team
- CPython’s internals
- Status of Python versions
- Python Contributor’s Guide (draft)
- [Plan for the Contributor’s Guide]
- Introduction
- The CPython project
- Issues and triaging
- Documentation contributions
- Code contributions
- Core team
- Accessibility, design, and user success
- Security and infrastructure contributions
- Workflows
Getting started¶
The Python language has a substantial body of documentation, much of itcontributed by various authors. The markup used for the Python documentation isreStructuredText, developed by thedocutils project, amended by customdirectives and using a toolset namedSphinx to post-process the HTML output.
The documentation in HTML, PDF or EPUB format is generated from text fileswritten using thereStructuredText format and contained in theCPython Git repository.
Note
If you’re interested in contributing to Python’s documentation, there’s noneed to write reStructuredText if you’re not so inclined; plain textcontributions are more than welcome as well. Send an e-mail todocs@python.org or open an issue on thetracker.
Introduction¶
Python’s documentation has long been considered to be good for a freeprogramming language. There are a number of reasons for this, the mostimportant being the early commitment of Python’s creator, Guido van Rossum, toproviding documentation on the language and its libraries, and the continuinginvolvement of the user community in providing assistance for creating andmaintaining documentation.
The involvement of the community takes many forms, from authoring to bug reportsto just plain complaining when the documentation could be more complete oreasier to use.
This section is aimed at authors and potential authors of documentation forPython. More specifically, it is for people contributing to the standarddocumentation and developing additional documents using the same tools as thestandard documents. This guide will be less useful for authors using the Pythondocumentation tools for topics other than Python, and less useful still forauthors not using the tools at all.
If your interest is in contributing to the Python documentation, but you don’thave the time or inclination to learn reStructuredText and the markup structuresdocumented here, there’s a welcoming place for you among the Python contributorsas well. Any time you feel that you can clarify existing documentation orprovide documentation that’s missing, the existing documentation team willgladly 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 documentationand 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 HTMLby opening the fileDoc/build/html/index.html in a web browser.
Note
The following instructions all assume your current working dir istheDoc subdirectory in yourCPython repository clone.Make sure to switch to it withcdDoc if necessary.
Create a virtual environment¶
You can create a newvenv with the required dependencies using:
makevenv
Building the docs withmake will automatically use this environmentwithout you having to activate it.
Create a new virtual environment manually.Always be sure toactivate this environmentbefore building the documentation.
Build using make / make.bat¶
A UnixMakefile is provided,Doc/Makefile.
A Windowsmake.bat is provided,Doc/make.bat, whichattempts to emulate the UnixMakefile as closely as practical.
Important
The Windowsmake.bat batch file lacks amakevenv target.Instead, it automatically installs any missing dependenciesinto the currently activated environment (or the base Python, if none).Make sure the environment youcreated aboveisactivated before runningmake.bat.
To build the docs as HTML, run:
makehtml
.\make html
Tip
Replace
htmlwithhtmlviewto open the docs in a web browseronce the build completes.Replace
htmlwithhtmlliveto rebuild the docs,start a local server, and automatically reload the page in yourbrowser when you make changes to reST files (Unix only).
It is also possible to build only certain pages of the documentation in orderto save time during the build process. Following is an example for building twopages:
makehtmlSOURCES="tutorial/classes.rst tutorial/inputoutput.rst"
SeeBuild using Sphinx directly. When invokingsphinx-build, pass thedesired pages as the final parameter, like so:
python -m sphinx -b html . build/html tutorial/classes.rst tutorial/inputoutput.rst
To check the docs for common errors withSphinx Lint(which is run on allpull requests), use:
makecheck
.\make check
To list other supportedmake targets, run:
makehelp.\make help
SeeDoc/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.
Make sure the environment youcreated aboveisactivated.Then, install the documentation requirements,Doc/requirements.txt.Using pip:
python-mpipinstall--upgrade-rrequirements.txt
Finally, directly invoke Sphinx with:
python-msphinx-bhtml.build/html
To use a differentSphinx builder,replacehtml above with the desired buildername.