[Python-checkins] devguide: move 'Documenting Python' doc section here
sandro.tosi
python-checkins at python.org
Sat Jan 14 19:01:09 CET 2012
http://hg.python.org/devguide/rev/5d4a90e568ed
changeset: 479:5d4a90e568ed
user: Sandro Tosi <sandro.tosi at gmail.com>
date: Sat Jan 14 18:58:47 2012 +0100
summary:
move 'Documenting Python' doc section here
files:
docquality.rst | 4 +-
documenting.rst | 1715 +++++++++++++++++++++++++++++++++++
index.rst | 1 +
patch.rst | 2 +-
4 files changed, 1718 insertions(+), 4 deletions(-)
diff --git a/docquality.rst b/docquality.rst
--- a/docquality.rst
+++ b/docquality.rst
@@ -8,7 +8,7 @@
appreciated with the documentation, and it requires little programming
experience (with or without Python).
-`Documenting Python`_ covers the details of how Python's documentation works.
+:ref:`Documenting Python <documenting>` covers the details of how Python's documentation works.
It includes an explanation of the markup used (although you can figure a lot
out simply by looking at pre-existing documentation) and how to build the
documentation (which allows you to see how your changes will look along with
@@ -32,8 +32,6 @@
<http://mail.python.org/mailman/listinfo/doc-sig>`_ which discusses the
documentation toolchain, projects, standards, etc.
-.. _Documenting Python: http://docs.python.org/dev/documenting/
-
Helping with issues filed on the issue tracker
----------------------------------------------
diff --git a/documenting.rst b/documenting.rst
new file mode 100644
--- /dev/null
+++ b/documenting.rst
@@ -0,0 +1,1715 @@
+.. _documenting:
+
+Documenting Python
+==================
+
+The Python language has a substantial body of documentation, much of it
+contributed by various authors. The markup used for the Python documentation is
+`reStructuredText`_, developed by the `docutils`_ project, amended by custom
+directives and using a toolset named `Sphinx`_ to postprocess the HTML output.
+
+This document describes the style guide for our documentation as well as the
+custom reStructuredText markup introduced by Sphinx to support Python
+documentation and how it should be used.
+
+.. _reStructuredText: http://docutils.sf.net/rst.html
+.. _docutils: http://docutils.sf.net/
+.. _Sphinx: http://sphinx.pocoo.org/
+
+.. note::
+
+ If you're interested in contributing to Python's documentation, there's no
+ need to write reStructuredText if you're not so inclined; plain text
+ contributions are more than welcome as well. Send an e-mail to
+ docs at python.org or open an issue on the :ref:`tracker <reporting-bugs>`.
+
+
+Introduction
+============
+
+Python's documentation has long been considered to be good for a free
+programming language. There are a number of reasons for this, the most
+important being the early commitment of Python's creator, Guido van Rossum, to
+providing documentation on the language and its libraries, and the continuing
+involvement of the user community in providing assistance for creating and
+maintaining documentation.
+
+The involvement of the community takes many forms, from authoring to bug reports
+to just plain complaining when the documentation could be more complete or
+easier to use.
+
+This document is aimed at authors and potential authors of documentation for
+Python. More specifically, it is for people contributing to the standard
+documentation and developing additional documents using the same tools as the
+standard documents. This guide will be less useful for authors using the Python
+documentation tools for topics other than Python, and less useful still for
+authors not using the tools at all.
+
+If your interest is in contributing to the Python documentation, but you don't
+have the time or inclination to learn reStructuredText and the markup structures
+documented here, there's a welcoming place for you among the Python contributors
+as well. Any time you feel that you can clarify existing documentation or
+provide documentation that's missing, the existing documentation team will
+gladly work with you to integrate your text, dealing with the markup for you.
+Please don't let the material in this document stand between the documentation
+and your desire to help out!
+
+
+Style guide
+===========
+
+The Python documentation should follow the `Apple Publications Style Guide`_
+wherever possible. This particular style guide was selected mostly because it
+seems reasonable and is easy to get online.
+
+Topics which are either not covered in Apple's style guide or treated
+differently in Python documentation will be discussed in this
+document.
+
+Use of whitespace
+-----------------
+
+All reST files use an indentation of 3 spaces; no tabs are allowed. The
+maximum line length is 80 characters for normal text, but tables, deeply
+indented code samples and long links may extend beyond that. Code example
+bodies should use normal Python 4-space indentation.
+
+Make generous use of blank lines where applicable; they help grouping things
+together.
+
+A sentence-ending period may be followed by one or two spaces; while reST
+ignores the second space, it is customarily put in by some users, for example
+to aid Emacs' auto-fill mode.
+
+Footnotes
+---------
+
+Footnotes are generally discouraged, though they may be used when they are the
+best way to present specific information. When a footnote reference is added at
+the end of the sentence, it should follow the sentence-ending punctuation. The
+reST markup should appear something like this::
+
+ This sentence has a footnote reference. [#]_ This is the next sentence.
+
+Footnotes should be gathered at the end of a file, or if the file is very long,
+at the end of a section. The docutils will automatically create backlinks to
+the footnote reference.
+
+Footnotes may appear in the middle of sentences where appropriate.
+
+Capitalization
+--------------
+
+.. sidebar:: Sentence case
+
+ Sentence case is a set of capitalization rules used in English
+ sentences: the first word is always capitalized and other words are
+ only capitalized if there is a specific rule requiring it.
+
+Apple style guide recommends the use of title case in section titles.
+However, rules for which words should be capitalized in title case
+vary greaty between publications.
+
+In Python documentation, use of sentence case in section titles is
+preferable, but consistency within a unit is more important than
+following this rule. If you add a section to the chapter where most
+sections are in title case you can either convert all titles to
+sentence case or use the dominant style in the new section title.
+
+Sentences that start with a word for which specific rules require
+starting it with a lower case letter should be avoided in titles and
+elsewhere.
+
+.. note::
+
+ Sections that describe a library module often have titles in the
+ form of "modulename --- Short description of the module." In this
+ case, the description should be capitalized as a stand-alone
+ sentence.
+
+Many special names are used in the Python documentation, including the names of
+operating systems, programming languages, standards bodies, and the like. Most
+of these entities are not assigned any special markup, but the preferred
+spellings are given here to aid authors in maintaining the consistency of
+presentation in the Python documentation.
+
+Other terms and words deserve special mention as well; these conventions should
+be used to ensure consistency throughout the documentation:
+
+CPU
+ For "central processing unit." Many style guides say this should be
+ spelled out on the first use (and if you must use it, do so!). For
+ the Python documentation, this abbreviation should be avoided since
+ there's no reasonable way to predict which occurrence will be the
+ first seen by the reader. It is better to use the word "processor"
+ instead.
+
+POSIX
+ The name assigned to a particular group of standards. This is always
+ uppercase.
+
+Python
+ The name of our favorite programming language is always capitalized.
+
+reST
+ For "reStructuredText," an easy to read, plaintext markup syntax
+ used to produce Python documentation. When spelled out, it is
+ always one word and both forms start with a lower case 'r'.
+
+Unicode
+ The name of a character coding system. This is always written
+ capitalized.
+
+Unix
+ The name of the operating system developed at AT&T Bell Labs in the early
+ 1970s.
+
+Affirmative Tone
+----------------
+
+The documentation focuses on affirmatively stating what the language does and
+how to use it effectively.
+
+Except for certain security risks or segfault risks, the docs should avoid
+wording along the lines of "feature x is dangerous" or "experts only". These
+kinds of value judgments belong in external blogs and wikis, not in the core
+documentation.
+
+Bad example (creating worry in the mind of a reader):
+
+ Warning: failing to explicitly close a file could result in lost data or
+ excessive resource consumption. Never rely on reference counting to
+ automatically close a file.
+
+Good example (establishing confident knowledge in the effective use of the language):
+
+ A best practice for using files is use a try/finally pair to explicitly
+ close a file after it is used. Alternatively, using a with-statement can
+ achieve the same effect. This assures that files are flushed and file
+ descriptor resources are released in a timely manner.
+
+Economy of Expression
+---------------------
+
+More documentation is not necessarily better documentation. Err on the side
+of being succinct.
+
+It is an unfortunate fact that making documentation longer can be an impediment
+to understanding and can result in even more ways to misread or misinterpret the
+text. Long descriptions full of corner cases and caveats can create the
+impression that a function is more complex or harder to use than it actually is.
+
+The documentation for :func:`super` is an example of where a good deal of
+information was condensed into a few short paragraphs. Discussion of
+:func:`super` could have filled a chapter in a book, but it is often easier to
+grasp a terse description than a lengthy narrative.
+
+
+Code Examples
+-------------
+
+Short code examples can be a useful adjunct to understanding. Readers can often
+grasp a simple example more quickly than they can digest a formal description in
+prose.
+
+People learn faster with concrete, motivating examples that match the context of
+a typical use case. For instance, the :func:`str.rpartition` method is better
+demonstrated with an example splitting the domain from a URL than it would be
+with an example of removing the last word from a line of Monty Python dialog.
+
+The ellipsis for the :attr:`sys.ps2` secondary interpreter prompt should only be
+used sparingly, where it is necessary to clearly differentiate between input
+lines and output lines. Besides contributing visual clutter, it makes it
+difficult for readers to cut-and-paste examples so they can experiment with
+variations.
+
+Code Equivalents
+----------------
+
+Giving pure Python code equivalents (or approximate equivalents) can be a useful
+adjunct to a prose description. A documenter should carefully weigh whether the
+code equivalent adds value.
+
+A good example is the code equivalent for :func:`all`. The short 4-line code
+equivalent is easily digested; it re-emphasizes the early-out behavior; and it
+clarifies the handling of the corner-case where the iterable is empty. In
+addition, it serves as a model for people wanting to implement a commonly
+requested alternative where :func:`all` would return the specific object
+evaluating to False whenever the function terminates early.
+
+A more questionable example is the code for :func:`itertools.groupby`. Its code
+equivalent borders on being too complex to be a quick aid to understanding.
+Despite its complexity, the code equivalent was kept because it serves as a
+model to alternative implementations and because the operation of the "grouper"
+is more easily shown in code than in English prose.
+
+An example of when not to use a code equivalent is for the :func:`oct` function.
+The exact steps in converting a number to octal doesn't add value for a user
+trying to learn what the function does.
+
+Audience
+--------
+
+The tone of the tutorial (and all the docs) needs to be respectful of the
+reader's intelligence. Don't presume that the readers are stupid. Lay out the
+relevant information, show motivating use cases, provide glossary links, and do
+your best to connect-the-dots, but don't talk down to them or waste their time.
+
+The tutorial is meant for newcomers, many of whom will be using the tutorial to
+evaluate the language as a whole. The experience needs to be positive and not
+leave the reader with worries that something bad will happen if they make a
+misstep. The tutorial serves as guide for intelligent and curious readers,
+saving details for the how-to guides and other sources.
+
+Be careful accepting requests for documentation changes from the rare but vocal
+category of reader who is looking for vindication for one of their programming
+errors ("I made a mistake, therefore the docs must be wrong ..."). Typically,
+the documentation wasn't consulted until after the error was made. It is
+unfortunate, but typically no documentation edit would have saved the user from
+making false assumptions about the language ("I was surprised by ...").
+
+
+.. _Apple Publications Style Guide: http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2009.pdf
+
+
+reStructuredText Primer
+=======================
+
+This section is a brief introduction to reStructuredText (reST) concepts and
+syntax, intended to provide authors with enough information to author documents
+productively. Since reST was designed to be a simple, unobtrusive markup
+language, this will not take too long.
+
+.. seealso::
+
+ The authoritative `reStructuredText User
+ Documentation <http://docutils.sourceforge.net/rst.html>`_.
+
+
+Paragraphs
+----------
+
+The paragraph is the most basic block in a reST document. Paragraphs are simply
+chunks of text separated by one or more blank lines. As in Python, indentation
+is significant in reST, so all lines of the same paragraph must be left-aligned
+to the same level of indentation.
+
+
+Inline markup
+-------------
+
+The standard reST inline markup is quite simple: use
+
+* one asterisk: ``*text*`` for emphasis (italics),
+* two asterisks: ``**text**`` for strong emphasis (boldface), and
+* backquotes: ````text```` for code samples.
+
+If asterisks or backquotes appear in running text and could be confused with
+inline markup delimiters, they have to be escaped with a backslash.
+
+Be aware of some restrictions of this markup:
+
+* it may not be nested,
+* content may not start or end with whitespace: ``* text*`` is wrong,
+* it must be separated from surrounding text by non-word characters. Use a
+ backslash escaped space to work around that: ``thisis\ *one*\ word``.
+
+These restrictions may be lifted in future versions of the docutils.
+
+reST also allows for custom "interpreted text roles"', which signify that the
+enclosed text should be interpreted in a specific way. Sphinx uses this to
+provide semantic markup and cross-referencing of identifiers, as described in
+the appropriate section. The general syntax is ``:rolename:`content```.
+
+
+Lists and Quotes
+----------------
+
+List markup is natural: just place an asterisk at the start of a paragraph and
+indent properly. The same goes for numbered lists; they can also be
+autonumbered using a ``#`` sign::
+
+ * This is a bulleted list.
+ * It has two items, the second
+ item uses two lines.
+
+ 1. This is a numbered list.
+ 2. It has two items too.
+
+ #. This is a numbered list.
+ #. It has two items too.
+
+
+Nested lists are possible, but be aware that they must be separated from the
+parent list items by blank lines::
+
+ * this is
+ * a list
+
+ * with a nested list
+ * and some subitems
+
+ * and here the parent list continues
+
+Definition lists are created as follows::
+
+ term (up to a line of text)
+ Definition of the term, which must be indented
+
+ and can even consist of multiple paragraphs
+
+ next term
+ Description.
+
+
+Paragraphs are quoted by just indenting them more than the surrounding
+paragraphs.
+
+
+Source Code
+-----------
+
+Literal code blocks are introduced by ending a paragraph with the special marker
+``::``. The literal block must be indented::
+
+ This is a normal text paragraph. The next paragraph is a code sample::
+
+ It is not processed in any way, except
+ that the indentation is removed.
+
+ It can span multiple lines.
+
+ This is a normal text paragraph again.
+
+The handling of the ``::`` marker is smart:
+
+* If it occurs as a paragraph of its own, that paragraph is completely left
+ out of the document.
+* If it is preceded by whitespace, the marker is removed.
+* If it is preceded by non-whitespace, the marker is replaced by a single
+ colon.
+
+That way, the second sentence in the above example's first paragraph would be
+rendered as "The next paragraph is a code sample:".
+
+
+Hyperlinks
+----------
+
+External links
+^^^^^^^^^^^^^^
+
+Use ```Link text <http://target>`_`` for inline web links. If the link text
+should be the web address, you don't need special markup at all, the parser
+finds links and mail addresses in ordinary text.
+
+Internal links
+^^^^^^^^^^^^^^
+
+Internal linking is done via a special reST role, see the section on specific
+markup, :ref:`doc-ref-role`.
+
+
+Sections
+--------
+
+Section headers are created by underlining (and optionally overlining) the
+section title with a punctuation character, at least as long as the text::
+
+ =================
+ This is a heading
+ =================
+
+Normally, there are no heading levels assigned to certain characters as the
+structure is determined from the succession of headings. However, for the
+Python documentation, we use this convention:
+
+* ``#`` with overline, for parts
+* ``*`` with overline, for chapters
+* ``=``, for sections
+* ``-``, for subsections
+* ``^``, for subsubsections
+* ``"``, for paragraphs
+
+
+Explicit Markup
+---------------
+
+"Explicit markup" is used in reST for most constructs that need special
+handling, such as footnotes, specially-highlighted paragraphs, comments, and
+generic directives.
+
+An explicit markup block begins with a line starting with ``..`` followed by
+whitespace and is terminated by the next paragraph at the same level of
+indentation. (There needs to be a blank line between explicit markup and normal
+paragraphs. This may all sound a bit complicated, but it is intuitive enough
+when you write it.)
+
+
+Directives
+----------
+
+A directive is a generic block of explicit markup. Besides roles, it is one of
+the extension mechanisms of reST, and Sphinx makes heavy use of it.
+
+Basically, a directive consists of a name, arguments, options and content. (Keep
+this terminology in mind, it is used in the next chapter describing custom
+directives.) Looking at this example, ::
+
+ .. function:: foo(x)
+ foo(y, z)
+ :bar: no
+
+ Return a line of text input from the user.
+
+``function`` is the directive name. It is given two arguments here, the
+remainder of the first line and the second line, as well as one option ``bar``
+(as you can see, options are given in the lines immediately following the
+arguments and indicated by the colons).
+
+The directive content follows after a blank line and is indented relative to the
+directive start.
+
+
+Footnotes
+---------
+
+For footnotes, use ``[#]_`` to mark the footnote location, and add the footnote
+body at the bottom of the document after a "Footnotes" rubric heading, like so::
+
+ Lorem ipsum [#]_ dolor sit amet ... [#]_
+
+ .. rubric:: Footnotes
+
+ .. [#] Text of the first footnote.
+ .. [#] Text of the second footnote.
+
+You can also explicitly number the footnotes for better context.
+
+
+Comments
+--------
+
+Every explicit markup block which isn't a valid markup construct (like the
+footnotes above) is regarded as a comment.
+
+
+Source encoding
+---------------
+
+Since the easiest way to include special characters like em dashes or copyright
+signs in reST is to directly write them as Unicode characters, one has to
+specify an encoding:
+
+All Python documentation source files must be in UTF-8 encoding, and the HTML
+documents written from them will be in that encoding as well.
+
+
+Gotchas
+-------
+
+There are some problems one commonly runs into while authoring reST documents:
+
+* **Separation of inline markup:** As said above, inline markup spans must be
+ separated from the surrounding text by non-word characters, you have to use
+ an escaped space to get around that.
+
+
+Additional Markup Constructs
+============================
+
+Sphinx adds a lot of new directives and interpreted text roles to standard reST
+markup. This section contains the reference material for these facilities.
+Documentation for "standard" reST constructs is not included here, though
+they are used in the Python documentation.
+
+.. note::
+
+ This is just an overview of Sphinx' extended markup capabilities; full
+ coverage can be found in `its own documentation
+ <http://sphinx.pocoo.org/contents.html>`_.
+
+
+Meta-information markup
+-----------------------
+
+.. describe:: sectionauthor
+
+ Identifies the author of the current section. The argument should include
+ the author's name such that it can be used for presentation (though it isn't)
+ and email address. The domain name portion of the address should be lower
+ case. Example::
+
+ .. sectionauthor:: Guido van Rossum <guido at python.org>
+
+ Currently, this markup isn't reflected in the output in any way, but it helps
+ keep track of contributions.
+
+
+Module-specific markup
+----------------------
+
+The markup described in this section is used to provide information about a
+module being documented. Each module should be documented in its own file.
+Normally this markup appears after the title heading of that file; a typical
+file might start like this::
+
+ :mod:`parrot` -- Dead parrot access
+ ===================================
+
+ .. module:: parrot
+ :platform: Unix, Windows
+ :synopsis: Analyze and reanimate dead parrots.
+ .. moduleauthor:: Eric Cleese <eric at python.invalid>
+ .. moduleauthor:: John Idle <john at python.invalid>
+
+As you can see, the module-specific markup consists of two directives, the
+``module`` directive and the ``moduleauthor`` directive.
+
+.. describe:: module
+
+ This directive marks the beginning of the description of a module, package,
+ or submodule. The name should be fully qualified (i.e. including the
+ package name for submodules).
+
+ The ``platform`` option, if present, is a comma-separated list of the
+ platforms on which the module is available (if it is available on all
+ platforms, the option should be omitted). The keys are short identifiers;
+ examples that are in use include "IRIX", "Mac", "Windows", and "Unix". It is
+ important to use a key which has already been used when applicable.
+
+ The ``synopsis`` option should consist of one sentence describing the
+ module's purpose -- it is currently only used in the Global Module Index.
+
+ The ``deprecated`` option can be given (with no value) to mark a module as
+ deprecated; it will be designated as such in various locations then.
+
+.. describe:: moduleauthor
+
+ The ``moduleauthor`` directive, which can appear multiple times, names the
+ authors of the module code, just like ``sectionauthor`` names the author(s)
+ of a piece of documentation. It too does not result in any output currently.
+
+.. note::
+
+ It is important to make the section title of a module-describing file
+ meaningful since that value will be inserted in the table-of-contents trees
+ in overview files.
+
+
+Information units
+-----------------
+
+There are a number of directives used to describe specific features provided by
+modules. Each directive requires one or more signatures to provide basic
+information about what is being described, and the content should be the
+description. The basic version makes entries in the general index; if no index
+entry is desired, you can give the directive option flag ``:noindex:``. The
+following example shows all of the features of this directive type::
+
+ .. function:: spam(eggs)
+ ham(eggs)
+ :noindex:
+
+ Spam or ham the foo.
+
+The signatures of object methods or data attributes should not include the
+class name, but be nested in a class directive. The generated files will
+reflect this nesting, and the target identifiers (for HTML output) will use
+both the class and method name, to enable consistent cross-references. If you
+describe methods belonging to an abstract protocol such as context managers,
+use a class directive with a (pseudo-)type name too to make the
+index entries more informative.
+
+The directives are:
+
+.. describe:: c:function
+
+ Describes a C function. The signature should be given as in C, e.g.::
+
+ .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+ This is also used to describe function-like preprocessor macros. The names
+ of the arguments should be given so they may be used in the description.
+
+ Note that you don't have to backslash-escape asterisks in the signature,
+ as it is not parsed by the reST inliner.
+
+.. describe:: c:member
+
+ Describes a C struct member. Example signature::
+
+ .. c:member:: PyObject* PyTypeObject.tp_bases
+
+ The text of the description should include the range of values allowed, how
+ the value should be interpreted, and whether the value can be changed.
+ References to structure members in text should use the ``member`` role.
+
+.. describe:: c:macro
+
+ Describes a "simple" C macro. Simple macros are macros which are used
+ for code expansion, but which do not take arguments so cannot be described as
+ functions. This is not to be used for simple constant definitions. Examples
+ of its use in the Python documentation include :c:macro:`PyObject_HEAD` and
+ :c:macro:`Py_BEGIN_ALLOW_THREADS`.
+
+.. describe:: c:type
+
+ Describes a C type. The signature should just be the type name.
+
+.. describe:: c:var
+
+ Describes a global C variable. The signature should include the type, such
+ as::
+
+ .. cvar:: PyObject* PyClass_Type
+
+.. describe:: data
+
+ Describes global data in a module, including both variables and values used
+ as "defined constants." Class and object attributes are not documented
+ using this directive.
+
+.. describe:: exception
+
+ Describes an exception class. The signature can, but need not include
+ parentheses with constructor arguments.
+
+.. describe:: function
+
+ Describes a module-level function. The signature should include the
+ parameters, enclosing optional parameters in brackets. Default values can be
+ given if it enhances clarity. For example::
+
+ .. function:: repeat([repeat=3[, number=1000000]])
+
+ Object methods are not documented using this directive. Bound object methods
+ placed in the module namespace as part of the public interface of the module
+ are documented using this, as they are equivalent to normal functions for
+ most purposes.
+
+ The description should include information about the parameters required and
+ how they are used (especially whether mutable objects passed as parameters
+ are modified), side effects, and possible exceptions. A small example may be
+ provided.
+
+.. describe:: decorator
+
+ Describes a decorator function. The signature should *not* represent the
+ signature of the actual function, but the usage as a decorator. For example,
+ given the functions
+
+ .. code-block:: python
+
+ def removename(func):
+ func.__name__ = ''
+ return func
+
+ def setnewname(name):
+ def decorator(func):
+ func.__name__ = name
+ return func
+ return decorator
+
+ the descriptions should look like this::
+
+ .. decorator:: removename
+
+ Remove name of the decorated function.
+
+ .. decorator:: setnewname(name)
+
+ Set name of the decorated function to *name*.
+
+ There is no ``deco`` role to link to a decorator that is marked up with
+ this directive; rather, use the ``:func:`` role.
+
+.. describe:: class
+
+ Describes a class. The signature can include parentheses with parameters
+ which will be shown as the constructor arguments.
+
+.. describe:: attribute
+
+ Describes an object data attribute. The description should include
+ information about the type of the data to be expected and whether it may be
+ changed directly. This directive should be nested in a class directive,
+ like in this example::
+
+ .. class:: Spam
+
+ Description of the class.
+
+ .. data:: ham
+
+ Description of the attribute.
+
+ If is also possible to document an attribute outside of a class directive,
+ for example if the documentation for different attributes and methods is
+ split in multiple sections. The class name should then be included
+ explicitly::
+
+ .. data:: Spam.eggs
+
+.. describe:: method
+
+ Describes an object method. The parameters should not include the ``self``
+ parameter. The description should include similar information to that
+ described for ``function``. This directive should be nested in a class
+ directive, like in the example above.
+
+.. describe:: decoratormethod
+
+ Same as ``decorator``, but for decorators that are methods.
+
+ Refer to a decorator method using the ``:meth:`` role.
+
+.. describe:: opcode
+
+ Describes a Python :term:`bytecode` instruction.
+
+.. describe:: cmdoption
+
+ Describes a Python command line option or switch. Option argument names
+ should be enclosed in angle brackets. Example::
+
+ .. cmdoption:: -m <module>
+
+ Run a module as a script.
+
+.. describe:: envvar
+
+ Describes an environment variable that Python uses or defines.
+
+
+There is also a generic version of these directives:
+
+.. describe:: describe
+
+ This directive produces the same formatting as the specific ones explained
+ above but does not create index entries or cross-referencing targets. It is
+ used, for example, to describe the directives in this document. Example::
+
+ .. describe:: opcode
+
+ Describes a Python bytecode instruction.
+
+
+Showing code examples
+---------------------
+
+Examples of Python source code or interactive sessions are represented using
+standard reST literal blocks. They are started by a ``::`` at the end of the
+preceding paragraph and delimited by indentation.
+
+Representing an interactive session requires including the prompts and output
+along with the Python code. No special markup is required for interactive
+sessions. After the last line of input or output presented, there should not be
+an "unused" primary prompt; this is an example of what *not* to do::
+
+ >>> 1 + 1
+ 2
+ >>>
+
+Syntax highlighting is handled in a smart way:
+
+* There is a "highlighting language" for each source file. Per default,
+ this is ``'python'`` as the majority of files will have to highlight Python
+ snippets.
+
+* Within Python highlighting mode, interactive sessions are recognized
+ automatically and highlighted appropriately.
+
+* The highlighting language can be changed using the ``highlightlang``
+ directive, used as follows::
+
+ .. highlightlang:: c
+
+ This language is used until the next ``highlightlang`` directive is
+ encountered.
+
+* The values normally used for the highlighting language are:
+
+ * ``python`` (the default)
+ * ``c``
+ * ``rest``
+ * ``none`` (no highlighting)
+
+* If highlighting with the current language fails, the block is not highlighted
+ in any way.
+
+Longer displays of verbatim text may be included by storing the example text in
+an external file containing only plain text. The file may be included using the
+``literalinclude`` directive. [1]_ For example, to include the Python source file
+:file:`example.py`, use::
+
+ .. literalinclude:: example.py
+
+The file name is relative to the current file's path. Documentation-specific
+include files should be placed in the ``Doc/includes`` subdirectory.
+
+
+Inline markup
+-------------
+
+As said before, Sphinx uses interpreted text roles to insert semantic markup in
+documents.
+
+Names of local variables, such as function/method arguments, are an exception,
+they should be marked simply with ``*var*``.
+
+For all other roles, you have to write ``:rolename:`content```.
+
+There are some additional facilities that make cross-referencing roles more
+versatile:
+
+* You may supply an explicit title and reference target, like in reST direct
+ hyperlinks: ``:role:`title <target>``` will refer to *target*, but the link
+ text will be *title*.
+
+* If you prefix the content with ``!``, no reference/hyperlink will be created.
+
+* For the Python object roles, if you prefix the content with ``~``, the link
+ text will only be the last component of the target. For example,
+ ``:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but only
+ display ``get`` as the link text.
+
+ In HTML output, the link's ``title`` attribute (that is e.g. shown as a
+ tool-tip on mouse-hover) will always be the full target name.
+
+The following roles refer to objects in modules and are possibly hyperlinked if
+a matching identifier is found:
+
+.. describe:: mod
+
+ The name of a module; a dotted name may be used. This should also be used for
+ package names.
+
+.. describe:: func
+
+ The name of a Python function; dotted names may be used. The role text
+ should not include trailing parentheses to enhance readability. The
+ parentheses are stripped when searching for identifiers.
+
+.. describe:: data
+
+ The name of a module-level variable or constant.
+
+.. describe:: const
+
+ The name of a "defined" constant. This may be a C-language ``#define``
+ or a Python variable that is not intended to be changed.
+
+.. describe:: class
+
+ A class name; a dotted name may be used.
+
+.. describe:: meth
+
+ The name of a method of an object. The role text should include the type
+ name and the method name. A dotted name may be used.
+
+.. describe:: attr
+
+ The name of a data attribute of an object.
+
+.. describe:: exc
+
+ The name of an exception. A dotted name may be used.
+
+The name enclosed in this markup can include a module name and/or a class name.
+For example, ``:func:`filter``` could refer to a function named ``filter`` in
+the current module, or the built-in function of that name. In contrast,
+``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo``
+module.
+
+Normally, names in these roles are searched first without any further
+qualification, then with the current module name prepended, then with the
+current module and class name (if any) prepended. If you prefix the name with a
+dot, this order is reversed. For example, in the documentation of the
+:mod:`codecs` module, ``:func:`open``` always refers to the built-in function,
+while ``:func:`.open``` refers to :func:`codecs.open`.
+
+A similar heuristic is used to determine whether the name is an attribute of
+the currently documented class.
+
+The following roles create cross-references to C-language constructs if they
+are defined in the API documentation:
+
+.. describe:: c:data
+
+ The name of a C-language variable.
+
+.. describe:: c:func
+
+ The name of a C-language function. Should include trailing parentheses.
+
+.. describe:: c:macro
+
+ The name of a "simple" C macro, as defined above.
+
+.. describe:: c:type
+
+ The name of a C-language type.
+
+.. describe:: c:member
+
+ The name of a C type member, as defined above.
+
+
+The following role does possibly create a cross-reference, but does not refer
+to objects:
+
+.. describe:: token
+
+ The name of a grammar token (used in the reference manual to create links
+ between production displays).
+
+
+The following role creates a cross-reference to the term in the glossary:
+
+.. describe:: term
+
+ Reference to a term in the glossary. The glossary is created using the
+ ``glossary`` directive containing a definition list with terms and
+ definitions. It does not have to be in the same file as the ``term``
+ markup, in fact, by default the Python docs have one global glossary
+ in the ``glossary.rst`` file.
+
+ If you use a term that's not explained in a glossary, you'll get a warning
+ during build.
+
+---------
+
+The following roles don't do anything special except formatting the text
+in a different style:
+
+.. describe:: command
+
+ The name of an OS-level command, such as ``rm``.
+
+.. describe:: dfn
+
+ Mark the defining instance of a term in the text. (No index entries are
+ generated.)
+
+.. describe:: envvar
+
+ An environment variable. Index entries are generated.
+
+.. describe:: file
+
+ The name of a file or directory. Within the contents, you can use curly
+ braces to indicate a "variable" part, for example::
+
+ ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
+
+ In the built documentation, the ``x`` will be displayed differently to
+ indicate that it is to be replaced by the Python minor version.
+
+.. describe:: guilabel
+
+ Labels presented as part of an interactive user interface should be marked
+ using ``guilabel``. This includes labels from text-based interfaces such as
+ those created using :mod:`curses` or other text-based libraries. Any label
+ used in the interface should be marked with this role, including button
+ labels, window titles, field names, menu and menu selection names, and even
+ values in selection lists.
+
+.. describe:: kbd
+
+ Mark a sequence of keystrokes. What form the key sequence takes may depend
+ on platform- or application-specific conventions. When there are no relevant
+ conventions, the names of modifier keys should be spelled out, to improve
+ accessibility for new users and non-native speakers. For example, an
+ *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without
+ reference to a specific application or platform, the same sequence should be
+ marked as ``:kbd:`Control-x Control-f```.
+
+.. describe:: keyword
+
+ The name of a Python keyword. Using this role will generate a link to the
+ documentation of the keyword. ``True``, ``False`` and ``None`` do not use
+ this role, but simple code markup (````True````), given that they're
+ fundamental to the language and should be known to any programmer.
+
+.. describe:: mailheader
+
+ The name of an RFC 822-style mail header. This markup does not imply that
+ the header is being used in an email message, but can be used to refer to any
+ header of the same "style." This is also used for headers defined by the
+ various MIME specifications. The header name should be entered in the same
+ way it would normally be found in practice, with the camel-casing conventions
+ being preferred where there is more than one common usage. For example:
+ ``:mailheader:`Content-Type```.
+
+.. describe:: makevar
+
+ The name of a :command:`make` variable.
+
+.. describe:: manpage
+
+ A reference to a Unix manual page including the section,
+ e.g. ``:manpage:`ls(1)```.
+
+.. describe:: menuselection
+
+ Menu selections should be marked using the ``menuselection`` role. This is
+ used to mark a complete sequence of menu selections, including selecting
+ submenus and choosing a specific operation, or any subsequence of such a
+ sequence. The names of individual selections should be separated by
+ ``-->``.
+
+ For example, to mark the selection "Start > Programs", use this markup::
+
+ :menuselection:`Start --> Programs`
+
+ When including a selection that includes some trailing indicator, such as the
+ ellipsis some operating systems use to indicate that the command opens a
+ dialog, the indicator should be omitted from the selection name.
+
+.. describe:: mimetype
+
+ The name of a MIME type, or a component of a MIME type (the major or minor
+ portion, taken alone).
+
+.. describe:: newsgroup
+
+ The name of a Usenet newsgroup.
+
+.. describe:: option
+
+ A command-line option of Python. The leading hyphen(s) must be included.
+ If a matching ``cmdoption`` directive exists, it is linked to. For options
+ of other programs or scripts, use simple ````code```` markup.
+
+.. describe:: program
+
+ The name of an executable program. This may differ from the file name for
+ the executable for some platforms. In particular, the ``.exe`` (or other)
+ extension should be omitted for Windows programs.
+
+.. describe:: regexp
+
+ A regular expression. Quotes should not be included.
+
+.. describe:: samp
+
+ A piece of literal text, such as code. Within the contents, you can use
+ curly braces to indicate a "variable" part, as in ``:file:``.
+
+ If you don't need the "variable part" indication, use the standard
+ ````code```` instead.
+
+
+The following roles generate external links:
+
+.. describe:: pep
+
+ A reference to a Python Enhancement Proposal. This generates appropriate
+ index entries. The text "PEP *number*\ " is generated; in the HTML output,
+ this text is a hyperlink to an online copy of the specified PEP.
+
+.. describe:: rfc
+
+ A reference to an Internet Request for Comments. This generates appropriate
+ index entries. The text "RFC *number*\ " is generated; in the HTML output,
+ this text is a hyperlink to an online copy of the specified RFC.
+
+
+Note that there are no special roles for including hyperlinks as you can use
+the standard reST markup for that purpose.
+
+
+.. _doc-ref-role:
+
+Cross-linking markup
+--------------------
+
+To support cross-referencing to arbitrary sections in the documentation, the
+standard reST labels are "abused" a bit: Every label must precede a section
+title; and every label name must be unique throughout the entire documentation
+source.
+
+You can then reference to these sections using the ``:ref:`label-name``` role.
+
+Example::
+
+ .. _my-reference-label:
+
+ Section to cross-reference
+ --------------------------
+
+ This is the text of the section.
+
+ It refers to the section itself, see :ref:`my-reference-label`.
+
+The ``:ref:`` invocation is replaced with the section title.
+
+Alternatively, you can reference any label (not just section titles)
+if you provide the link text ``:ref:`link text <reference-label>```.
+
+Paragraph-level markup
+----------------------
+
+These directives create short paragraphs and can be used inside information
+units as well as normal text:
+
+.. describe:: note
+
+ An especially important bit of information about an API that a user should be
+ aware of when using whatever bit of API the note pertains to. The content of
+ the directive should be written in complete sentences and include all
+ appropriate punctuation.
+
+ Example::
+
+ .. note::
+
+ This function is not suitable for sending spam e-mails.
+
+.. describe:: warning
+
+ An important bit of information about an API that a user should be aware of
+ when using whatever bit of API the warning pertains to. The content of the
+ directive should be written in complete sentences and include all appropriate
+ punctuation. In the interest of not scaring users away from pages filled
+ with warnings, this directive should only be chosen over ``note`` for
+ information regarding the possibility of crashes, data loss, or security
+ implications.
+
+.. describe:: versionadded
+
+ This directive documents the version of Python which added the described
+ feature to the library or C API. When this applies to an entire module, it
+ should be placed at the top of the module section before any prose.
+
+ The first argument must be given and is the version in question; you can add
+ a second argument consisting of a *brief* explanation of the change.
+
+ Example::
+
+ .. versionadded:: 3.1
+ The *spam* parameter.
+
+ Note that there must be no blank line between the directive head and the
+ explanation; this is to make these blocks visually continuous in the markup.
+
+.. describe:: versionchanged
+
+ Similar to ``versionadded``, but describes when and what changed in the named
+ feature in some way (new parameters, changed side effects, etc.).
+
+--------------
+
+.. describe:: impl-detail
+
+ This directive is used to mark CPython-specific information. Use either with
+ a block content or a single sentence as an argument, i.e. either ::
+
+ .. impl-detail::
+
+ This describes some implementation detail.
+
+ More explanation.
+
+ or ::
+
+ .. impl-detail:: This shortly mentions an implementation detail.
+
+ "\ **CPython implementation detail:**\ " is automatically prepended to the
+ content.
+
+.. describe:: seealso
+
+ Many sections include a list of references to module documentation or
+ external documents. These lists are created using the ``seealso`` directive.
+
+ The ``seealso`` directive is typically placed in a section just before any
+ sub-sections. For the HTML output, it is shown boxed off from the main flow
+ of the text.
+
+ The content of the ``seealso`` directive should be a reST definition list.
+ Example::
+
+ .. seealso::
+
+ Module :mod:`zipfile`
+ Documentation of the :mod:`zipfile` standard module.
+
+ `GNU tar manual, Basic Tar Format <http://link>`_
+ Documentation for tar archive files, including GNU tar extensions.
+
+.. describe:: rubric
+
+ This directive creates a paragraph heading that is not used to create a
+ table of contents node. It is currently used for the "Footnotes" caption.
+
+.. describe:: centered
+
+ This directive creates a centered boldfaced paragraph. Use it as follows::
+
+ .. centered::
+
+ Paragraph contents.
+
+
+Table-of-contents markup
+------------------------
+
+Since reST does not have facilities to interconnect several documents, or split
+documents into multiple output files, Sphinx uses a custom directive to add
+relations between the single files the documentation is made of, as well as
+tables of contents. The ``toctree`` directive is the central element.
+
+.. describe:: toctree
+
+ This directive inserts a "TOC tree" at the current location, using the
+ individual TOCs (including "sub-TOC trees") of the files given in the
+ directive body. A numeric ``maxdepth`` option may be given to indicate the
+ depth of the tree; by default, all levels are included.
+
+ Consider this example (taken from the library reference index)::
+
+ .. toctree::
+ :maxdepth: 2
+
+ intro
+ strings
+ datatypes
+ numeric
+ (many more files listed here)
+
+ This accomplishes two things:
+
+ * Tables of contents from all those files are inserted, with a maximum depth
+ of two, that means one nested heading. ``toctree`` directives in those
+ files are also taken into account.
+ * Sphinx knows that the relative order of the files ``intro``,
+ ``strings`` and so forth, and it knows that they are children of the
+ shown file, the library index. From this information it generates "next
+ chapter", "previous chapter" and "parent chapter" links.
+
+ In the end, all files included in the build process must occur in one
+ ``toctree`` directive; Sphinx will emit a warning if it finds a file that is
+ not included, because that means that this file will not be reachable through
+ standard navigation.
+
+ The special file ``contents.rst`` at the root of the source directory is the
+ "root" of the TOC tree hierarchy; from it the "Contents" page is generated.
+
+
+Index-generating markup
+-----------------------
+
+Sphinx automatically creates index entries from all information units (like
+functions, classes or attributes) like discussed before.
+
+However, there is also an explicit directive available, to make the index more
+comprehensive and enable index entries in documents where information is not
+mainly contained in information units, such as the language reference.
+
+The directive is ``index`` and contains one or more index entries. Each entry
+consists of a type and a value, separated by a colon.
+
+For example::
+
+ .. index::
+ single: execution; context
+ module: __main__
+ module: sys
+ triple: module; search; path
+
+This directive contains five entries, which will be converted to entries in the
+generated index which link to the exact location of the index statement (or, in
+case of offline media, the corresponding page number).
+
+The possible entry types are:
+
+single
+ Creates a single index entry. Can be made a subentry by separating the
+ subentry text with a semicolon (this notation is also used below to describe
+ what entries are created).
+pair
+ ``pair: loop; statement`` is a shortcut that creates two index entries,
+ namely ``loop; statement`` and ``statement; loop``.
+triple
+ Likewise, ``triple: module; search; path`` is a shortcut that creates three
+ index entries, which are ``module; search path``, ``search; path, module`` and
+ ``path; module search``.
+module, keyword, operator, object, exception, statement, builtin
+ These all create two index entries. For example, ``module: hashlib`` creates
+ the entries ``module; hashlib`` and ``hashlib; module``.
+
+For index directives containing only "single" entries, there is a shorthand
+notation::
+
+ .. index:: BNF, grammar, syntax, notation
+
+This creates four index entries.
+
+
+Grammar production displays
+---------------------------
+
+Special markup is available for displaying the productions of a formal grammar.
+The markup is simple and does not attempt to model all aspects of BNF (or any
+derived forms), but provides enough to allow context-free grammars to be
+displayed in a way that causes uses of a symbol to be rendered as hyperlinks to
+the definition of the symbol. There is this directive:
+
+.. describe:: productionlist
+
+ This directive is used to enclose a group of productions. Each production is
+ given on a single line and consists of a name, separated by a colon from the
+ following definition. If the definition spans multiple lines, each
+ continuation line must begin with a colon placed at the same column as in the
+ first line.
+
+ Blank lines are not allowed within ``productionlist`` directive arguments.
+
+ The definition can contain token names which are marked as interpreted text
+ (e.g. ``unaryneg ::= "-" `integer```) -- this generates cross-references
+ to the productions of these tokens.
+
+ Note that no further reST parsing is done in the production, so that you
+ don't have to escape ``*`` or ``|`` characters.
+
+
+.. XXX describe optional first parameter
+
+The following is an example taken from the Python Reference Manual::
+
+ .. productionlist::
+ try_stmt: try1_stmt | try2_stmt
+ try1_stmt: "try" ":" `suite`
+ : ("except" [`expression` ["," `target`]] ":" `suite`)+
+ : ["else" ":" `suite`]
+ : ["finally" ":" `suite`]
+ try2_stmt: "try" ":" `suite`
+ : "finally" ":" `suite`
+
+
+Substitutions
+-------------
+
+The documentation system provides three substitutions that are defined by default.
+They are set in the build configuration file :file:`conf.py`.
+
+.. describe:: |release|
+
+ Replaced by the Python release the documentation refers to. This is the full
+ version string including alpha/beta/release candidate tags, e.g. ``2.5.2b3``.
+
+.. describe:: |version|
+
+ Replaced by the Python version the documentation refers to. This consists
+ only of the major and minor version parts, e.g. ``2.5``, even for version
+ 2.5.1.
+
+.. describe:: |today|
+
+ Replaced by either today's date, or the date set in the build configuration
+ file. Normally has the format ``April 14, 2007``.
+
+
+.. rubric:: Footnotes
+
+.. [1] There is a standard ``.. include`` directive, but it raises errors if the
+ file is not found. This one only emits a warning.
+
+
+Differences to the LaTeX markup
+===============================
+
+Though the markup language is different, most of the concepts and markup types
+of the old LaTeX docs have been kept -- environments as reST directives, inline
+commands as reST roles and so forth.
+
+However, there are some differences in the way these work, partly due to the
+differences in the markup languages, partly due to improvements in Sphinx. This
+section lists these differences, in order to give those familiar with the old
+format a quick overview of what they might run into.
+
+Inline markup
+-------------
+
+These changes have been made to inline markup:
+
+* **Cross-reference roles**
+
+ Most of the following semantic roles existed previously as inline commands,
+ but didn't do anything except formatting the content as code. Now, they
+ cross-reference to known targets (some names have also been shortened):
+
+ | *mod* (previously *refmodule* or *module*)
+ | *func* (previously *function*)
+ | *data* (new)
+ | *const*
+ | *class*
+ | *meth* (previously *method*)
+ | *attr* (previously *member*)
+ | *exc* (previously *exception*)
+ | *cdata*
+ | *cfunc* (previously *cfunction*)
+ | *cmacro* (previously *csimplemacro*)
+ | *ctype*
+
+ Also different is the handling of *func* and *meth*: while previously
+ parentheses were added to the callable name (like ``\func{str()}``), they are
+ now appended by the build system -- appending them in the source will result
+ in double parentheses. This also means that ``:func:`str(object)``` will not
+ work as expected -- use ````str(object)```` instead!
+
+* **Inline commands implemented as directives**
+
+ These were inline commands in LaTeX, but are now directives in reST:
+
+ | *deprecated*
+ | *versionadded*
+ | *versionchanged*
+
+ These are used like so::
+
+ .. deprecated:: 2.5
+ Reason of deprecation.
+
+ Also, no period is appended to the text for *versionadded* and
+ *versionchanged*.
+
+ | *note*
+ | *warning*
+
+ These are used like so::
+
+ .. note::
+
+ Content of note.
+
+* **Otherwise changed commands**
+
+ The *samp* command previously formatted code and added quotation marks around
+ it. The *samp* role, however, features a new highlighting system just like
+ *file* does:
+
+ ``:samp:`open({filename}, {mode})``` results in :samp:`open({filename}, {mode})`
+
+* **Dropped commands**
+
+ These were commands in LaTeX, but are not available as roles:
+
+ | *bfcode*
+ | *character* (use :samp:`\`\`'c'\`\``)
+ | *citetitle* (use ```Title <URL>`_``)
+ | *code* (use ````code````)
+ | *email* (just write the address in body text)
+ | *filenq*
+ | *filevar* (use the ``{...}`` highlighting feature of *file*)
+ | *programopt*, *longprogramopt* (use *option*)
+ | *ulink* (use ```Title <URL>`_``)
+ | *url* (just write the URL in body text)
+ | *var* (use ``*var*``)
+ | *infinity*, *plusminus* (use the Unicode character)
+ | *shortversion*, *version* (use the ``|version|`` and ``|release|`` substitutions)
+ | *emph*, *strong* (use the reST markup)
+
+* **Backslash escaping**
+
+ In reST, a backslash must be escaped in normal text, and in the content of
+ roles. However, in code literals and literal blocks, it must not be escaped.
+ Example: ``:file:`C:\\Temp\\my.tmp``` vs. ````open("C:\Temp\my.tmp")````.
+
+
+Information units
+-----------------
+
+Information units (*...desc* environments) have been made reST directives.
+These changes to information units should be noted:
+
+* **New names**
+
+ "desc" has been removed from every name. Additionally, these directives have
+ new names:
+
+ | *cfunction* (previously *cfuncdesc*)
+ | *cmacro* (previously *csimplemacrodesc*)
+ | *exception* (previously *excdesc*)
+ | *function* (previously *funcdesc*)
+ | *attribute* (previously *memberdesc*)
+
+ The *classdesc\** and *excclassdesc* environments have been dropped, the
+ *class* and *exception* directives support classes documented with and without
+ constructor arguments.
+
+* **Multiple objects**
+
+ The equivalent of the *...line* commands is::
+
+ .. function:: do_foo(bar)
+ do_bar(baz)
+
+ Description of the functions.
+
+ IOW, just give one signatures per line, at the same indentation level.
+
+* **Arguments**
+
+ There is no *optional* command. Just give function signatures like they
+ should appear in the output::
+
+ .. function:: open(filename[, mode[, buffering]])
+
+ Description.
+
+ Note: markup in the signature is not supported.
+
+* **Indexing**
+
+ The *...descni* environments have been dropped. To mark an information unit
+ as unsuitable for index entry generation, use the *noindex* option like so::
+
+ .. function:: foo_*
+ :noindex:
+
+ Description.
+
+* **New information units**
+
+ There are new generic information units: One is called "describe" and can be
+ used to document things that are not covered by the other units::
+
+ .. describe:: a == b
+
+ The equals operator.
+
+ The others are::
+
+ .. cmdoption:: -O
+
+ Describes a command-line option.
+
+ .. envvar:: PYTHONINSPECT
+
+ Describes an environment variable.
+
+
+Structure
+---------
+
+The LaTeX docs were split in several toplevel manuals. Now, all files are part
+of the same documentation tree, as indicated by the *toctree* directives in the
+sources (though individual output formats may choose to split them up into parts
+again). Every *toctree* directive embeds other files as subdocuments of the
+current file (this structure is not necessarily mirrored in the filesystem
+layout). The toplevel file is :file:`contents.rst`.
+
+However, most of the old directory structure has been kept, with the
+directories renamed as follows:
+
+* :file:`api` -> :file:`c-api`
+* :file:`dist` -> :file:`distutils`, with the single TeX file split up
+* :file:`doc` -> :file:`documenting`
+* :file:`ext` -> :file:`extending`
+* :file:`inst` -> :file:`installing`
+* :file:`lib` -> :file:`library`
+* :file:`mac` -> merged into :file:`library`, with :file:`mac/using.tex`
+ moved to :file:`using/mac.rst`
+* :file:`ref` -> :file:`reference`
+* :file:`tut` -> :file:`tutorial`, with the single TeX file split up
+
+
+.. XXX more (index-generating, production lists, ...)
+
+
+Building the documentation
+==========================
+
+You need to have Python 2.4 or higher installed; the toolset used to build the
+docs is written in Python. It is called *Sphinx*, it is not included in this
+tree, but maintained separately. Also needed are the docutils, supplying the
+base markup that Sphinx uses, Jinja, a templating engine, and optionally
+Pygments, a code highlighter.
+
+
+Using make
+----------
+
+Luckily, a Makefile has been prepared so that on Unix, provided you have
+installed Python and Subversion, you can just run ::
+
+ cd Doc
+ make html
+
+to check out the necessary toolset in the :file:`tools/` subdirectory and build
+the HTML output files. To view the generated HTML, point your favorite browser
+at the top-level index :file:`build/html/index.html` after running "make".
+
+Available make targets are:
+
+ * "html", which builds standalone HTML files for offline viewing.
+
+ * "htmlhelp", which builds HTML files and a HTML Help project file usable to
+ convert them into a single Compiled HTML (.chm) file -- these are popular
+ under Microsoft Windows, but very handy on every platform.
+
+ To create the CHM file, you need to run the Microsoft HTML Help Workshop
+ over the generated project (.hhp) file.
+
+ * "latex", which builds LaTeX source files as input to "pdflatex" to produce
+ PDF documents.
+
+ * "text", which builds a plain text file for each source file.
+
+ * "linkcheck", which checks all external references to see whether they are
+ broken, redirected or malformed, and outputs this information to stdout
+ as well as a plain-text (.txt) file.
+
+ * "changes", which builds an overview over all versionadded/versionchanged/
+ deprecated items in the current version. This is meant as a help for the
+ writer of the "What's New" document.
+
+ * "coverage", which builds a coverage overview for standard library modules
+ and C API.
+
+ * "pydoc-topics", which builds a Python module containing a dictionary with
+ plain text documentation for the labels defined in
+ :file:`tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and
+ keyword help.
+
+A "make update" updates the Subversion checkouts in :file:`tools/`.
+
+
+Without make
+------------
+
+You'll need to install the Sphinx package, either by checking it out via ::
+
+ svn co http://svn.python.org/projects/external/Sphinx-0.6.5/sphinx tools/sphinx
+
+or by installing it from PyPI.
+
+Then, you need to install Docutils, either by checking it out via ::
+
+ svn co http://svn.python.org/projects/external/docutils-0.6/docutils tools/docutils
+
+or by installing it from http://docutils.sf.net/.
+
+You also need Jinja2, either by checking it out via ::
+
+ svn co http://svn.python.org/projects/external/Jinja-2.3.1/jinja2 tools/jinja2
+
+or by installing it from PyPI.
+
+You can optionally also install Pygments, either as a checkout via ::
+
+ svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments
+
+or from PyPI at http://pypi.python.org/pypi/Pygments.
+
+
+Then, make an output directory, e.g. under `build/`, and run ::
+
+ python tools/sphinx-build.py -b<builder> . build/<outputdirectory>
+
+where `<builder>` is one of html, text, latex, or htmlhelp (for explanations see
+the make targets above).
diff --git a/index.rst b/index.rst
--- a/index.rst
+++ b/index.rst
@@ -10,6 +10,7 @@
runtests
coverage
docquality
+ documenting
silencewarnings
fixingissues
helptriage
diff --git a/patch.rst b/patch.rst
--- a/patch.rst
+++ b/patch.rst
@@ -92,7 +92,7 @@
test seems impacted by your changes, because there might be interferences
unknown to you between your changes and some other part of the interpreter.
-Fifth, proper `documentation <http://docs.python.org/dev/documenting/>`_
+Fifth, proper :ref:`documentation <documenting>`
additions/changes should be included.
Sixth, if you are not already in the ``Misc/ACKS`` file then add your name. If
--
Repository URL: http://hg.python.org/devguide
More information about the Python-checkins
mailing list