[Python-checkins] r61399 - in doctools/trunk/doc: concepts.rst contents.rst glossary.rst markup markup.rst markup/code.rst markup/index.rst markup/infounits.rst markup/inline.rst markup/misc.rst markup/para.rst
georg.brandl
python-checkins at python.org
Sat Mar 15 10:06:05 CET 2008
Author: georg.brandl
Date: Sat Mar 15 10:06:04 2008
New Revision: 61399
Added:
doctools/trunk/doc/markup/
doctools/trunk/doc/markup/code.rst
doctools/trunk/doc/markup/index.rst
doctools/trunk/doc/markup/infounits.rst
doctools/trunk/doc/markup/inline.rst
doctools/trunk/doc/markup/misc.rst
doctools/trunk/doc/markup/para.rst
Removed:
doctools/trunk/doc/markup.rst
Modified:
doctools/trunk/doc/concepts.rst
doctools/trunk/doc/contents.rst
doctools/trunk/doc/glossary.rst
Log:
Expand the markup chapter a bit.
Modified: doctools/trunk/doc/concepts.rst
==============================================================================
--- doctools/trunk/doc/concepts.rst (original)
+++ doctools/trunk/doc/concepts.rst Sat Mar 15 10:06:04 2008
@@ -1,14 +1,58 @@
+.. highlight:: rest
+
.. _concepts:
Sphinx concepts
===============
+Document names
+--------------
-The TOC tree
-------------
-Document names
---------------
+The TOC tree
+------------
+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.
+
+.. directive:: 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 Python docs' library reference index)::
+
+ .. toctree::
+ :maxdepth: 2
+
+ intro.rst
+ strings.rst
+ datatypes.rst
+ numeric.rst
+ (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.rst``,
+ ``strings.rst`` 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. Use :confval:`unused_documents` to explicitly exclude
+ documents from this check.
+
+ The "master file" (selected by :confval:`master_file`) is the "root" of the
+ TOC tree hierarchy. It can be used as the documentation's main page, or as a
+ "full table of contents" if you don't give a ``maxdepth`` option.
Modified: doctools/trunk/doc/contents.rst
==============================================================================
--- doctools/trunk/doc/contents.rst (original)
+++ doctools/trunk/doc/contents.rst Sat Mar 15 10:06:04 2008
@@ -9,7 +9,7 @@
intro.rst
concepts.rst
rest.rst
- markup.rst
+ markup/index.rst
builders.rst
config.rst
templating.rst
Modified: doctools/trunk/doc/glossary.rst
==============================================================================
--- doctools/trunk/doc/glossary.rst (original)
+++ doctools/trunk/doc/glossary.rst Sat Mar 15 10:06:04 2008
@@ -20,3 +20,9 @@
documentation root
The directory which contains the documentation's :file:`conf.py` file and
is therefore seen as one Sphinx project.
+
+ environment
+ A structure where information about all documents under the root is saved,
+ and used for cross-referencing. The environment is pickled after the
+ parsing stage, so that successive runs only need to read and parse new and
+ changed documents.
Deleted: /doctools/trunk/doc/markup.rst
==============================================================================
--- /doctools/trunk/doc/markup.rst Sat Mar 15 10:06:04 2008
+++ (empty file)
@@ -1,835 +0,0 @@
-.. highlight:: rest
- :linenothreshold: 5
-
-.. XXX missing: glossary
-
-
-Sphinx 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.
-
-
-File-wide metadata
-------------------
-
-reST has the concept of "field lists"; these are a sequence of fields marked up
-like this::
-
- :Field name: Field content
-
-A field list at the very top of a file is parsed as the "docinfo", which in
-normal documents can be used to record the author, date of publication and
-other metadata. In Sphinx, the docinfo is used as metadata, too, but not
-displayed in the output.
-
-At the moment, only one metadata field is recognized:
-
-``nocomments``
- If set, the web application won't display a comment form for a page generated
- from this source file.
-
-
-Meta-information markup
------------------------
-
-.. directive:: sectionauthor
-
- Identifies the author of the current section. The argument should include
- the author's name such that it can be used for presentation and email
- address. The domain name portion of the address should be lower case.
- Example::
-
- .. sectionauthor:: Guido van Rossum <guido at python.org>
-
- By default, this markup isn't reflected in the output in any way (it helps
- keep track of contributions), but you can set the configuration value
- :confval:`show_authors` to True to make them produce a paragraph in the
- output.
-
-
-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.
-
-.. directive:: module
-
- This directive marks the beginning of the description of a module (or package
- submodule, in which case the name should be fully qualified, including the
- package name).
-
- 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.
-
-.. directive:: 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 only produces output if the
- :confval:`show_authors` configuration value is True.
-
-
-.. 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 always include the
-type name (``.. method:: FileInput.input(...)``), even if it is obvious from the
-context which type they belong to; this is to enable consistent
-cross-references. If you describe methods belonging to an abstract protocol,
-such as "context managers", include a (pseudo-)type name too to make the
-index entries more informative.
-
-The directives are:
-
-.. directive:: cfunction
-
- Describes a C function. The signature should be given as in C, e.g.::
-
- .. cfunction:: 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.
-
-.. directive:: cmember
-
- Describes a C struct member. Example signature::
-
- .. cmember:: 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.
-
-.. directive:: cmacro
-
- 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 :cmacro:`PyObject_HEAD` and
- :cmacro:`Py_BEGIN_ALLOW_THREADS`.
-
-.. directive:: ctype
-
- Describes a C type. The signature should just be the type name.
-
-.. directive:: cvar
-
- Describes a global C variable. The signature should include the type, such
- as::
-
- .. cvar:: PyObject* PyClass_Type
-
-.. directive:: 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 environment.
-
-.. directive:: exception
-
- Describes an exception class. The signature can, but need not include
- parentheses with constructor arguments.
-
-.. directive:: 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:: Timer.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.
-
-.. directive:: class
-
- Describes a class. The signature can include parentheses with parameters
- which will be shown as the constructor arguments.
-
-.. directive:: 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.
-
-.. directive:: method
-
- Describes an object method. The parameters should not include the ``self``
- parameter. The description should include similar information to that
- described for ``function``.
-
-.. directive:: opcode
-
- Describes a Python bytecode instruction (this is not very useful for projects
- other than Python itself).
-
-.. directive:: cmdoption
-
- Describes a command line option or switch. Option argument names should be
- enclosed in angle brackets. Example::
-
- .. cmdoption:: -m <module>
-
- Run a module as a script.
-
-.. directive:: envvar
-
- Describes an environment variable that the documented code uses or defines.
-
-
-There is also a generic version of these directives:
-
-.. directive:: 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 valid values 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.
-
-Variable names are an exception, they should be marked simply with ``*var*``.
-
-For all other roles, you have to write ``:rolename:`content```.
-
-.. note::
-
- For all cross-referencing roles, if you prefix the content with ``!``, no
- reference/hyperlink will be created.
-
-The following roles refer to objects in modules and are possibly hyperlinked if
-a matching identifier is found:
-
-.. role:: mod
-
- The name of a module; a dotted name may be used. This should also be used for
- package names.
-
-.. role:: func
-
- The name of a Python function; dotted names may be used. The role text
- should include trailing parentheses to enhance readability. The parentheses
- are stripped when searching for identifiers.
-
-.. role:: data
-
- The name of a module-level variable.
-
-.. role:: 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.
-
-.. role:: class
-
- A class name; a dotted name may be used.
-
-.. role:: meth
-
- The name of a method of an object. The role text should include the type
- name, method name and the trailing parentheses. A dotted name may be used.
-
-.. role:: attr
-
- The name of a data attribute of an object.
-
-.. role:: 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:
-
-.. role:: cdata
-
- The name of a C-language variable.
-
-.. role:: cfunc
-
- The name of a C-language function. Should include trailing parentheses.
-
-.. role:: cmacro
-
- The name of a "simple" C macro, as defined above.
-
-.. role:: ctype
-
- The name of a C-language type.
-
-
-The following roles do possibly create a cross-reference, but do not refer
-to objects:
-
-.. role:: token
-
- The name of a grammar token (used in the reference manual to create links
- between production displays).
-
-.. role:: keyword
-
- The name of a keyword in Python. This creates a link to a reference label
- with that name, if it exists.
-
-
-The following role creates a cross-reference to the term in the glossary:
-
-.. role:: 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,
- for example 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:
-
-.. role:: command
-
- The name of an OS-level command, such as ``rm``.
-
-.. role:: dfn
-
- Mark the defining instance of a term in the text. (No index entries are
- generated.)
-
-.. role:: envvar
-
- An environment variable. Index entries are generated.
-
-.. role:: 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.
-
-.. role:: 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.
-
-.. role:: 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```.
-
-.. role:: 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```.
-
-.. role:: makevar
-
- The name of a :command:`make` variable.
-
-.. role:: manpage
-
- A reference to a Unix manual page including the section,
- e.g. ``:manpage:`ls(1)```.
-
-.. role:: 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.
-
-.. role:: mimetype
-
- The name of a MIME type, or a component of a MIME type (the major or minor
- portion, taken alone).
-
-.. role:: newsgroup
-
- The name of a Usenet newsgroup.
-
-.. role:: option
-
- A command-line option to an executable program. The leading hyphen(s) must
- be included.
-
-.. role:: 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.
-
-.. role:: regexp
-
- A regular expression. Quotes should not be included.
-
-.. role:: 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.
-
-.. role:: var
-
- A Python or C variable or parameter name.
-
-
-The following roles generate external links:
-
-.. role:: 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.
-
-.. role:: 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
---------------------
-
-.. XXX add new :ref: syntax alternative
-
-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.
-
-
-Paragraph-level markup
-----------------------
-
-These directives create short paragraphs and can be used inside information
-units as well as normal text:
-
-.. directive:: 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.
-
-.. directive:: warning
-
- An important bit of information about an API that a user should be very 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. This differs from ``note`` in that it is recommended
- over ``note`` for information regarding security.
-
-.. directive:: versionadded
-
- This directive documents the version of the project 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:: 2.5
- 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.
-
-.. directive:: versionchanged
-
- Similar to ``versionadded``, but describes when and what changed in the named
- feature in some way (new parameters, changed side effects, etc.).
-
---------------
-
-.. directive:: 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.
-
-.. directive:: 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.
-
-.. directive:: 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.
-
-.. directive:: 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.rst
- strings.rst
- datatypes.rst
- numeric.rst
- (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.rst``,
- ``strings.rst`` 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:
-
-.. directive:: 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. ``sum ::= `integer` "+" `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, see :ref:`doc-build-config`.
-
-.. describe:: |release|
-
- Replaced by the project release the documentation refers to. This is meant
- to be the full version string including alpha/beta/release candidate tags,
- e.g. ``2.5.2b3``.
-
-.. describe:: |version|
-
- Replaced by the project version the documentation refers to. This is meant to
- consist 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.
Added: doctools/trunk/doc/markup/code.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/doc/markup/code.rst Sat Mar 15 10:06:04 2008
@@ -0,0 +1,94 @@
+.. highlight:: rest
+
+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 done with `Pygments <http://pygments.org>`_ (if it's
+installed) and 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 ``highlight`` directive,
+ used as follows::
+
+ .. highlight:: c
+
+ This language is used until the next ``highlight`` directive is encountered.
+
+* For documents that have to show snippets in different languages, there's also
+ a :dir:`code-block` directive that is given the highlighting language
+ directly::
+
+ .. code-block:: ruby
+
+ Some Ruby code.
+
+ The directive's alias name :dir:`sourcecode` works as well.
+
+* The valid values for the highlighting language are:
+
+ * ``none`` (no highlighting)
+ * ``python`` (the default)
+ * ``rest``
+ * ``c``
+ * ... and any other lexer name that Pygments supports.
+
+* If highlighting with the selected language fails, the block is not highlighted
+ in any way.
+
+Line numbers
+^^^^^^^^^^^^
+
+If installed, Pygments can generate line numbers for code blocks. For
+automatically-highlighted blocks (those started by ``::``), line numbers must be
+switched on in a :dir:`highlight` directive, with the ``linenothreshold``
+option::
+
+ .. highlight:: python
+ :linenothreshold: 5
+
+This will produce line numbers for all code blocks longer than five lines.
+
+For :dir:`code-block` blocks, a ``linenos`` flag option can be given to switch
+on line numbers for the individual block::
+
+ .. code-block:: ruby
+ :linenos:
+
+ Some more Ruby code.
+
+
+Includes
+^^^^^^^^
+
+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.
+
+
+.. 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.
Added: doctools/trunk/doc/markup/index.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/doc/markup/index.rst Sat Mar 15 10:06:04 2008
@@ -0,0 +1,15 @@
+.. XXX missing: glossary
+
+Sphinx 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.
+
+.. toctree::
+
+ infounits.rst
+ para.rst
+ code.rst
+ inline.rst
+ misc.rst
Added: doctools/trunk/doc/markup/infounits.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/doc/markup/infounits.rst Sat Mar 15 10:06:04 2008
@@ -0,0 +1,197 @@
+.. highlight:: rest
+
+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.
+
+.. directive:: module
+
+ This directive marks the beginning of the description of a module (or package
+ submodule, in which case the name should be fully qualified, including the
+ package name).
+
+ 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.
+
+.. directive:: 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 only produces output if the
+ :confval:`show_authors` configuration value is True.
+
+
+.. 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 always include the
+type name (``.. method:: FileInput.input(...)``), even if it is obvious from the
+context which type they belong to; this is to enable consistent
+cross-references. If you describe methods belonging to an abstract protocol,
+such as "context managers", include a (pseudo-)type name too to make the
+index entries more informative.
+
+The directives are:
+
+.. directive:: cfunction
+
+ Describes a C function. The signature should be given as in C, e.g.::
+
+ .. cfunction:: 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.
+
+.. directive:: cmember
+
+ Describes a C struct member. Example signature::
+
+ .. cmember:: 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.
+
+.. directive:: cmacro
+
+ 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 :cmacro:`PyObject_HEAD` and
+ :cmacro:`Py_BEGIN_ALLOW_THREADS`.
+
+.. directive:: ctype
+
+ Describes a C type. The signature should just be the type name.
+
+.. directive:: cvar
+
+ Describes a global C variable. The signature should include the type, such
+ as::
+
+ .. cvar:: PyObject* PyClass_Type
+
+.. directive:: 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 environment.
+
+.. directive:: exception
+
+ Describes an exception class. The signature can, but need not include
+ parentheses with constructor arguments.
+
+.. directive:: 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:: Timer.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.
+
+.. directive:: class
+
+ Describes a class. The signature can include parentheses with parameters
+ which will be shown as the constructor arguments.
+
+.. directive:: 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.
+
+.. directive:: method
+
+ Describes an object method. The parameters should not include the ``self``
+ parameter. The description should include similar information to that
+ described for ``function``.
+
+.. directive:: opcode
+
+ Describes a Python bytecode instruction (this is not very useful for projects
+ other than Python itself).
+
+.. directive:: cmdoption
+
+ Describes a command line option or switch. Option argument names should be
+ enclosed in angle brackets. Example::
+
+ .. cmdoption:: -m <module>
+
+ Run a module as a script.
+
+.. directive:: envvar
+
+ Describes an environment variable that the documented code uses or defines.
+
+
+There is also a generic version of these directives:
+
+.. directive:: 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.
Added: doctools/trunk/doc/markup/inline.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/doc/markup/inline.rst Sat Mar 15 10:06:04 2008
@@ -0,0 +1,311 @@
+.. highlight:: rest
+
+Inline markup
+-------------
+
+As said before, Sphinx uses interpreted text roles to insert semantic markup in
+documents.
+
+Variable names are an exception, they should be marked simply with ``*var*``.
+
+For all other roles, you have to write ``:rolename:`content```.
+
+.. note::
+
+ For all cross-referencing roles, if you prefix the content with ``!``, no
+ reference/hyperlink will be created.
+
+The following roles refer to objects in modules and are possibly hyperlinked if
+a matching identifier is found:
+
+.. role:: mod
+
+ The name of a module; a dotted name may be used. This should also be used for
+ package names.
+
+.. role:: func
+
+ The name of a Python function; dotted names may be used. The role text
+ should include trailing parentheses to enhance readability. The parentheses
+ are stripped when searching for identifiers.
+
+.. role:: data
+
+ The name of a module-level variable.
+
+.. role:: 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.
+
+.. role:: class
+
+ A class name; a dotted name may be used.
+
+.. role:: meth
+
+ The name of a method of an object. The role text should include the type
+ name, method name and the trailing parentheses. A dotted name may be used.
+
+.. role:: attr
+
+ The name of a data attribute of an object.
+
+.. role:: 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:
+
+.. role:: cdata
+
+ The name of a C-language variable.
+
+.. role:: cfunc
+
+ The name of a C-language function. Should include trailing parentheses.
+
+.. role:: cmacro
+
+ The name of a "simple" C macro, as defined above.
+
+.. role:: ctype
+
+ The name of a C-language type.
+
+
+The following roles do possibly create a cross-reference, but do not refer
+to objects:
+
+.. role:: token
+
+ The name of a grammar token (used in the reference manual to create links
+ between production displays).
+
+.. role:: keyword
+
+ The name of a keyword in Python. This creates a link to a reference label
+ with that name, if it exists.
+
+
+The following role creates a cross-reference to the term in the glossary:
+
+.. role:: 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,
+ for example 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:
+
+.. role:: command
+
+ The name of an OS-level command, such as ``rm``.
+
+.. role:: dfn
+
+ Mark the defining instance of a term in the text. (No index entries are
+ generated.)
+
+.. role:: envvar
+
+ An environment variable. Index entries are generated.
+
+.. role:: 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.
+
+.. role:: 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.
+
+.. role:: 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```.
+
+.. role:: 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```.
+
+.. role:: makevar
+
+ The name of a :command:`make` variable.
+
+.. role:: manpage
+
+ A reference to a Unix manual page including the section,
+ e.g. ``:manpage:`ls(1)```.
+
+.. role:: 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.
+
+.. role:: mimetype
+
+ The name of a MIME type, or a component of a MIME type (the major or minor
+ portion, taken alone).
+
+.. role:: newsgroup
+
+ The name of a Usenet newsgroup.
+
+.. role:: option
+
+ A command-line option to an executable program. The leading hyphen(s) must
+ be included.
+
+.. role:: 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.
+
+.. role:: regexp
+
+ A regular expression. Quotes should not be included.
+
+.. role:: 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.
+
+.. role:: var
+
+ A Python or C variable or parameter name.
+
+
+The following roles generate external links:
+
+.. role:: 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.
+
+.. role:: 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.
+
+
+Substitutions
+-------------
+
+The documentation system provides three substitutions that are defined by default.
+They are set in the build configuration file.
+
+.. describe:: |release|
+
+ Replaced by the project release the documentation refers to. This is meant
+ to be the full version string including alpha/beta/release candidate tags,
+ e.g. ``2.5.2b3``. Set by :confval:`release`.
+
+.. describe:: |version|
+
+ Replaced by the project version the documentation refers to. This is meant to
+ consist only of the major and minor version parts, e.g. ``2.5``, even for
+ version 2.5.1. Set by :confval:`version`.
+
+.. describe:: |today|
+
+ Replaced by either today's date, or the date set in the build configuration
+ file. Normally has the format ``April 14, 2007``. Set by
+ :confval:`today_fmt` and :confval:`today`.
+
+
+.. _doc-ref-role:
+
+Cross-linking markup
+--------------------
+
+To support cross-referencing to arbitrary sections in the documentation, the
+standard reST labels used. Of course, for this to work label names must be
+unique throughout the entire documentation. There are two ways in which you can
+refer to labels:
+
+* If you place a label directly before a section title, you can reference to it
+ with ``:ref:`label-name```. 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:`` role would then generate a link to the section, with the link
+ title being "Section to cross-reference".
+
+* Labels that aren't placed before a section title can still be referenced to,
+ but you must give the link an explicit title, using this syntax: ``:ref:`Link
+ title <label-name>```.
Added: doctools/trunk/doc/markup/misc.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/doc/markup/misc.rst Sat Mar 15 10:06:04 2008
@@ -0,0 +1,41 @@
+.. highlight:: rest
+
+Miscellaneous markup
+====================
+
+File-wide metadata
+------------------
+
+reST has the concept of "field lists"; these are a sequence of fields marked up
+like this::
+
+ :Field name: Field content
+
+A field list at the very top of a file is parsed as the "docinfo", which in
+normal documents can be used to record the author, date of publication and
+other metadata. In Sphinx, the docinfo is used as metadata, too, but not
+displayed in the output.
+
+At the moment, only one metadata field is recognized:
+
+``nocomments``
+ If set, the web application won't display a comment form for a page generated
+ from this source file.
+
+
+Meta-information markup
+-----------------------
+
+.. directive:: sectionauthor
+
+ Identifies the author of the current section. The argument should include
+ the author's name such that it can be used for presentation and email
+ address. The domain name portion of the address should be lower case.
+ Example::
+
+ .. sectionauthor:: Guido van Rossum <guido at python.org>
+
+ By default, this markup isn't reflected in the output in any way (it helps
+ keep track of contributions), but you can set the configuration value
+ :confval:`show_authors` to True to make them produce a paragraph in the
+ output.
Added: doctools/trunk/doc/markup/para.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/doc/markup/para.rst Sat Mar 15 10:06:04 2008
@@ -0,0 +1,185 @@
+.. highlight:: rest
+
+Paragraph-level markup
+----------------------
+
+These directives create short paragraphs and can be used inside information
+units as well as normal text:
+
+.. directive:: 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.
+
+.. directive:: warning
+
+ An important bit of information about an API that a user should be very 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. This differs from ``note`` in that it is recommended
+ over ``note`` for information regarding security.
+
+.. directive:: versionadded
+
+ This directive documents the version of the project 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:: 2.5
+ 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.
+
+.. directive:: versionchanged
+
+ Similar to ``versionadded``, but describes when and what changed in the named
+ feature in some way (new parameters, changed side effects, etc.).
+
+--------------
+
+.. directive:: 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.
+
+.. directive:: 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.
+
+.. directive:: centered
+
+ This directive creates a centered boldfaced paragraph. Use it as follows::
+
+ .. centered::
+
+ Paragraph contents.
+
+
+Table-of-contents markup
+------------------------
+
+The :dir:`toctree` directive, which generates tables of contents of
+subdocuments, is described in "Sphinx concepts".
+
+For local tables of contents, use the standard reST :dir:`contents` directive.
+
+
+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:
+
+.. directive:: 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. ``sum ::= `integer` "+" `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`
More information about the Python-checkins
mailing list