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 at <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" chapter of the 10developers guide <https://docs.python.org/devguide/documenting.html>. 11 12 13Building the docs 14================= 15 16You need to have Sphinx <http://sphinx-doc.org/> installed; it is the toolset 17used to build the docs. It is not included in this tree, but maintained 18separately and available from PyPI <https://pypi.python.org/pypi/Sphinx>. 19 20 21Using make 22---------- 23 24A Makefile has been prepared so that on Unix, provided you have installed 25Sphinx, you can just run :: 26 27 make html 28 29to build the HTML output files. 30 31On Windows, we try to emulate the Makefile as closely as possible with a 32``make.bat`` file. 33 34To use a Python interpreter that's not called ``python``, use the standard 35way to set Makefile variables, using e.g. :: 36 37 make html PYTHON=python3 38 39On Windows, set the PYTHON environment variable instead. 40 41To use a specific sphinx-build (something other than ``sphinx-build``), set 42the SPHINXBUILD variable. 43 44Available make targets are: 45 46* "clean", which removes all build files. 47 48* "html", which builds standalone HTML files for offline viewing. 49 50* "htmlview", which re-uses the "html" builder, but then opens the main page 51 in your default web browser. 52 53* "htmlhelp", which builds HTML files and a HTML Help project file usable to 54 convert them into a single Compiled HTML (.chm) file -- these are popular 55 under Microsoft Windows, but very handy on every platform. 56 57 To create the CHM file, you need to run the Microsoft HTML Help Workshop 58 over the generated project (.hhp) file. The make.bat script does this for 59 you on Windows. 60 61* "latex", which builds LaTeX source files as input to "pdflatex" to produce 62 PDF documents. 63 64* "text", which builds a plain text file for each source file. 65 66* "epub", which builds an EPUB document, suitable to be viewed on e-book 67 readers. 68 69* "linkcheck", which checks all external references to see whether they are 70 broken, redirected or malformed, and outputs this information to stdout as 71 well as a plain-text (.txt) file. 72 73* "changes", which builds an overview over all versionadded/versionchanged/ 74 deprecated items in the current version. This is meant as a help for the 75 writer of the "What's New" document. 76 77* "coverage", which builds a coverage overview for standard library modules and 78 C API. 79 80* "pydoc-topics", which builds a Python module containing a dictionary with 81 plain text documentation for the labels defined in 82 `tools/pyspecific.py` -- pydoc needs these to show topic and keyword help. 83 84* "suspicious", which checks the parsed markup for text that looks like 85 malformed and thus unconverted reST. 86 87* "check", which checks for frequent markup errors. 88 89* "serve", which serves the build/html directory on port 8000. 90 91* "dist", (Unix only) which creates distributable archives of HTML, text, 92 PDF, and EPUB builds. 93 94 95Without make 96------------ 97 98Install the Sphinx package and its dependencies from PyPI. 99 100Then, from the ``Doc`` directory, run :: 101 102 sphinx-build -b<builder> . build/<builder> 103 104where ``<builder>`` is one of html, text, latex, or htmlhelp (for explanations 105see the make targets above). 106 107 108Contributing 109============ 110 111Bugs in the content should be reported to the Python bug tracker at 112https://bugs.python.org. 113 114Bugs in the toolset should be reported in the Sphinx bug tracker at 115https://www.bitbucket.org/birkenfeld/sphinx/issues/. 116 117You can also send a mail to the Python Documentation Team at docs@python.org, 118and we will process your request as soon as possible. 119 120If you want to help the Documentation Team, you are always welcome. Just send 121a mail to docs@python.org. 122