blob: 4f8e9f8f1417fbc2de630e2759c6e35a83735a2b [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
5documentation. You don't need to build them yourself, prebuilt versions are
Senthil Kumarandb599882014-04-09 11:45:14 -04006available at <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
Georg Brandl116aa622007-08-15 14:28:22 +00009both style and markup, is available in the "Documenting Python" chapter of the
Georg Brandl69a72032014-10-29 08:18:43 +010010developers guide <https://docs.python.org/devguide/documenting.html>.
Georg Brandl116aa622007-08-15 14:28:22 +000011
12
13Building the docs
14=================
15
Georg Brandl02e77d12014-03-10 19:31:52 +010016You 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
Georg Brandl69a72032014-10-29 08:18:43 +010018separately and available from PyPI <https://pypi.python.org/pypi/Sphinx>.
Georg Brandl116aa622007-08-15 14:28:22 +000019
20
21Using make
22----------
23
Georg Brandl02e77d12014-03-10 19:31:52 +010024A Makefile has been prepared so that on Unix, provided you have installed
25Sphinx, you can just run ::
Georg Brandl116aa622007-08-15 14:28:22 +000026
27 make html
28
Zachary Ware1de519c2014-04-29 09:26:56 -050029to build the HTML output files.
Georg Brandl116aa622007-08-15 14:28:22 +000030
Georg Brandl18a364f2014-03-10 19:26:57 +010031On Windows, we try to emulate the Makefile as closely as possible with a
32``make.bat`` file.
Georg Brandl116aa622007-08-15 14:28:22 +000033
Georg Brandl716c3ac2007-08-30 18:34:23 +000034To use a Python interpreter that's not called ``python``, use the standard
35way to set Makefile variables, using e.g. ::
36
Zachary Ware1de519c2014-04-29 09:26:56 -050037 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.
Georg Brandl716c3ac2007-08-30 18:34:23 +000043
Georg Brandl116aa622007-08-15 14:28:22 +000044Available make targets are:
45
Georg Brandl69a72032014-10-29 08:18:43 +010046* "clean", which removes all build files.
Zachary Ware1de519c2014-04-29 09:26:56 -050047
Georg Brandl69a72032014-10-29 08:18:43 +010048* "html", which builds standalone HTML files for offline viewing.
Georg Brandl116aa622007-08-15 14:28:22 +000049
Georg Brandl69a72032014-10-29 08:18:43 +010050* "htmlview", which re-uses the "html" builder, but then opens the main page
51 in your default web browser.
Zachary Ware1de519c2014-04-29 09:26:56 -050052
Georg Brandl69a72032014-10-29 08:18:43 +010053* "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.
Georg Brandl116aa622007-08-15 14:28:22 +000056
Georg Brandl69a72032014-10-29 08:18:43 +010057 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.
Georg Brandl116aa622007-08-15 14:28:22 +000060
Georg Brandl69a72032014-10-29 08:18:43 +010061* "latex", which builds LaTeX source files as input to "pdflatex" to produce
62 PDF documents.
Christian Heimes3feef612008-02-11 06:19:17 +000063
Georg Brandl69a72032014-10-29 08:18:43 +010064* "text", which builds a plain text file for each source file.
Georg Brandl0c77a822008-06-10 16:37:50 +000065
Georg Brandl69a72032014-10-29 08:18:43 +010066* "epub", which builds an EPUB document, suitable to be viewed on e-book
67 readers.
Georg Brandl183fe812011-01-05 11:00:25 +000068
Georg Brandl69a72032014-10-29 08:18:43 +010069* "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.
Christian Heimesd8654cf2007-12-02 15:22:16 +000072
Georg Brandl69a72032014-10-29 08:18:43 +010073* "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.
Christian Heimes5b5e81c2007-12-31 16:14:33 +000076
Georg Brandl69a72032014-10-29 08:18:43 +010077* "coverage", which builds a coverage overview for standard library modules and
78 C API.
Christian Heimesd3eb5a152008-02-24 00:38:49 +000079
Georg Brandl69a72032014-10-29 08:18:43 +010080* "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.
Georg Brandl6b38daa2008-06-01 21:05:17 +000083
Georg Brandl69a72032014-10-29 08:18:43 +010084* "suspicious", which checks the parsed markup for text that looks like
85 malformed and thus unconverted reST.
Georg Brandl116aa622007-08-15 14:28:22 +000086
Georg Brandl69a72032014-10-29 08:18:43 +010087* "check", which checks for frequent markup errors.
Zachary Ware1de519c2014-04-29 09:26:56 -050088
Georg Brandl69a72032014-10-29 08:18:43 +010089* "serve", which serves the build/html directory on port 8000.
Zachary Ware1de519c2014-04-29 09:26:56 -050090
Georg Brandl69a72032014-10-29 08:18:43 +010091* "dist", (Unix only) which creates distributable archives of HTML, text,
92 PDF, and EPUB builds.
Zachary Ware1de519c2014-04-29 09:26:56 -050093
Georg Brandl116aa622007-08-15 14:28:22 +000094
95Without make
96------------
97
Georg Brandl18a364f2014-03-10 19:26:57 +010098Install the Sphinx package and its dependencies from PyPI.
Georg Brandl116aa622007-08-15 14:28:22 +000099
Zachary Warea37ff0f2014-04-18 15:10:40 -0500100Then, from the ``Doc`` directory, run ::
Georg Brandld94b4a72010-03-13 10:56:09 +0000101
Georg Brandl18a364f2014-03-10 19:26:57 +0100102 sphinx-build -b<builder> . build/<builder>
Georg Brandl116aa622007-08-15 14:28:22 +0000103
Georg Brandl18a364f2014-03-10 19:26:57 +0100104where ``<builder>`` is one of html, text, latex, or htmlhelp (for explanations
105see the make targets above).
Georg Brandl116aa622007-08-15 14:28:22 +0000106
107
108Contributing
109============
110
Benjamin Peterson92035012008-12-27 16:00:54 +0000111Bugs in the content should be reported to the Python bug tracker at
Georg Brandl69a72032014-10-29 08:18:43 +0100112https://bugs.python.org.
Georg Brandl116aa622007-08-15 14:28:22 +0000113
Benjamin Peterson92035012008-12-27 16:00:54 +0000114Bugs in the toolset should be reported in the Sphinx bug tracker at
Georg Brandl69a72032014-10-29 08:18:43 +0100115https://www.bitbucket.org/birkenfeld/sphinx/issues/.
Georg Brandl116aa622007-08-15 14:28:22 +0000116
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.