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 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