Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 145 lines (91 sloc) 4.951 kB
6e978f2 @jdhardy Add Python 2.7.2 documentation.
authored
1 Python Documentation README
2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
3
4 This directory contains the reStructuredText (reST) sources to the Python
5 documentation. You don't need to build them yourself, prebuilt versions are
6 available at http://docs.python.org/download/.
7
8 Documentation on the authoring Python documentation, including information about
9 both style and markup, is available in the "Documenting Python" chapter of the
10 documentation. There's also a chapter intended to point out differences to
11 those familiar with the previous docs written in LaTeX.
12
13
14 Building the docs
15 =================
16
17 You need to have Python 2.4 or higher installed; the toolset used to build the
18 docs is written in Python. It is called *Sphinx*, it is not included in this
19 tree, but maintained separately. Also needed are the docutils, supplying the
20 base markup that Sphinx uses, Jinja, a templating engine, and optionally
21 Pygments, a code highlighter.
22
23
24 Using make
25 ----------
26
27 Luckily, a Makefile has been prepared so that on Unix, provided you have
28 installed Python and Subversion, you can just run ::
29
30 make html
31
32 to check out the necessary toolset in the `tools/` subdirectory and build the
33 HTML output files. To view the generated HTML, point your favorite browser at
34 the top-level index `build/html/index.html` after running "make".
35
36 Available make targets are:
37
38 * "html", which builds standalone HTML files for offline viewing.
39
40 * "htmlhelp", which builds HTML files and a HTML Help project file usable to
41 convert them into a single Compiled HTML (.chm) file -- these are popular
42 under Microsoft Windows, but very handy on every platform.
43
44 To create the CHM file, you need to run the Microsoft HTML Help Workshop over
45 the generated project (.hhp) file.
46
47 * "latex", which builds LaTeX source files as input to "pdflatex" to produce
48 PDF documents.
49
50 * "text", which builds a plain text file for each source file.
51
52 * "linkcheck", which checks all external references to see whether they are
53 broken, redirected or malformed, and outputs this information to stdout as
54 well as a plain-text (.txt) file.
55
56 * "changes", which builds an overview over all versionadded/versionchanged/
57 deprecated items in the current version. This is meant as a help for the
58 writer of the "What's New" document.
59
60 * "coverage", which builds a coverage overview for standard library modules and
61 C API.
62
63 * "pydoc-topics", which builds a Python module containing a dictionary with
64 plain text documentation for the labels defined in
65 `tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and
66 keyword help.
67
68 A "make update" updates the Subversion checkouts in `tools/`.
69
70
71 Without make
72 ------------
73
74 You'll need to install the Sphinx package, either by checking it out via ::
75
76 svn co http://svn.python.org/projects/external/Sphinx-0.6.7/sphinx tools/sphinx
77
78 or by installing it from PyPI.
79
80 Then, you need to install Docutils, either by checking it out via ::
81
82 svn co http://svn.python.org/projects/external/docutils-0.6/docutils tools/docutils
83
84 or by installing it from http://docutils.sf.net/.
85
86 You also need Jinja2, either by checking it out via ::
87
88 svn co http://svn.python.org/projects/external/Jinja-2.3.1/jinja2 tools/jinja2
89
90 or by installing it from PyPI.
91
92 You can optionally also install Pygments, either as a checkout via ::
93
94 svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments
95
96 or from PyPI at http://pypi.python.org/pypi/Pygments.
97
98
99 Then, make an output directory, e.g. under `build/`, and run ::
100
101 python tools/sphinx-build.py -b<builder> . build/<outputdirectory>
102
103 where `<builder>` is one of html, text, latex, or htmlhelp (for explanations see
104 the make targets above).
105
106
107 Contributing
108 ============
109
110 Bugs in the content should be reported to the Python bug tracker at
111 http://bugs.python.org.
112
113 Bugs in the toolset should be reported in the Sphinx bug tracker at
114 http://www.bitbucket.org/birkenfeld/sphinx/issues/.
115
116 You can also send a mail to the Python Documentation Team at docs@python.org,
117 and we will process your request as soon as possible.
118
119 If you want to help the Documentation Team, you are always welcome. Just send
120 a mail to docs@python.org.
121
122
123 Copyright notice
124 ================
125
126 The Python source is copyrighted, but you can freely use and copy it
127 as long as you don't change or remove the copyright notice:
128
129 ----------------------------------------------------------------------
130 Copyright (c) 2000-2008 Python Software Foundation.
131 All rights reserved.
132
133 Copyright (c) 2000 BeOpen.com.
134 All rights reserved.
135
136 Copyright (c) 1995-2000 Corporation for National Research Initiatives.
137 All rights reserved.
138
139 Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
140 All rights reserved.
141
142 See the file "license.rst" for information on usage and redistribution
143 of this file, and for a DISCLAIMER OF ALL WARRANTIES.
144 ----------------------------------------------------------------------
Something went wrong with that request. Please try again.