Anonymous avatar Anonymous committed 4ca916f

Update documentation, add more content.

Comments (0)

Files changed (16)

 .. _builders:
 
-Builders and the environment
-============================
+Available builders
+==================
 
 .. module:: sphinx.builder
    :synopsis: Available built-in builder classes.
 
+These are the built-in Sphinx builders.  More builders can be added by
+:ref:`extensions <extensions>`.
 
-.. class:: Builder
+The builder's "name" must be given to the **-b** command-line option of
+:program:`sphinx-build.py` to select a builder.
+
 
 .. class:: StandaloneHTMLBuilder
 
-.. class:: WebHTMLBuilder
+   This is the standard HTML builder.  Its output is a directory with HTML
+   files, complete with style sheets and optionally the reST sources.  There are
+   quite a few configuration values that customize the output of this builder,
+   see the chapter :ref:`html-options` for details.
+
+   Its name is ``html``.
 
 .. class:: HTMLHelpBuilder
 
+   This builder produces the same output as the standalone HTML builder, but
+   also generates HTML Help support files that allow the Microsoft HTML Help
+   Workshop to compile them into a CHM file.
+
+   Its name is ``htmlhelp``. 
+
+.. class:: WebHTMLBuilder
+
+   This builder produces a directory with pickle files containing mostly HTML
+   fragments and TOC information, for use of a web application (or custom
+   postprocessing tool) that doesn't use the standard HTML templates.
+
+   It also is the format used by the Sphinx Web application.  Its name is
+   ``web``.
+
 .. class:: LaTeXBuilder
 
+   This builder produces a bunch of LaTeX files in the output directory.  You
+   have to specify which documents are to be included in which LaTeX files via
+   the :confval:`latex_documents` configuration value.  There are a few
+   configuration values that customize the output of this builder, see the
+   chapter :ref:`latex-options` for details.
+
+   Its name is ``latex``.
+
 .. class:: ChangesBuilder
 
+   This builder produces an HTML overview of all :dir:`versionadded`,
+   :dir:`versionchanged` and :dir:`deprecated` directives for the current
+   :confval:`version`.  This is useful to generate a ChangeLog file, for
+   example.
+
+   Its name is ``changes``.
+
 .. class:: CheckExternalLinksBuilder
 
+   This builder scans all documents for external links, tries to open them with
+   :mod:`urllib2`, and writes an overview which ones are broken and redirected
+   to standard output and to :file:`output.txt` in the output directory.
+
+   Its name is ``linkcheck``.
+
 Document names
 --------------
 
-
+Since the reST source files can have different extensions (some people like
+``.txt``, some like ``.rst`` -- the extension can be configured with
+:confval:`source_suffix`) and different OSes have different path separators,
+Sphinx abstracts them: all "document names" are relative to the
+:term:`documentation root`, the extension is stripped, and path separators are
+converted to slashes.  All values, parameters and suchlike referring to
+"documents" expect such a document name.
 
 
 The TOC tree
 ------------
 
+.. index:: pair: table of; contents
+
 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
 .. 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.
+   individual TOCs (including "sub-TOC trees") of the documents given in the
+   directive body (whose path is relative to the document the directive occurs
+   in).  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)
+         intro
+         strings
+         datatypes
+         numeric
+         (many more documents 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
+   * Tables of contents from all those documents are inserted, with a maximum
+     depth of two, that means one nested heading.  ``toctree`` directives in
+     those documents are also taken into account.
+   * Sphinx knows that the relative order of the documents ``intro``,
+     ``strings`` and so forth, and it knows that they are children of the shown
+     document, 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.
+   In the end, all documents under the :term:`documentation root` 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.
+   The "master document" (selected by :confval:`master_doc`) 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.
    style.
 
 
+.. _html-options:
+
 Options for HTML output
 -----------------------
 
    Output file base name for HTML help builder.  Default is ``'pydoc'``.
 
 
+.. _latex-options:
+
 Options for LaTeX output
 ------------------------
 
 .. toctree::
    :maxdepth: 1
 
-   intro.rst
-   concepts.rst
-   rest.rst
-   markup/index.rst
-   builders.rst
-   config.rst
-   templating.rst
-   extensions.rst
+   intro
+   concepts
+   rest
+   markup/index
+   builders
+   config
+   templating
+   extensions
    
-   glossary.rst
+   glossary
 
 
 Indices and tables
+# -*- coding: utf-8 -*-
+"""
+    ext.py -- Sphinx extension for the Sphinx documentation
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    :copyright: 2008 by Georg Brandl.
+    :license: BSD.
+"""
+
+import re
+
+from sphinx import addnodes
+
+dir_sig_re = re.compile(r'\.\. ([^:]+)::(.*)$')
+
+def parse_directive(sig, signode):
+    if not sig.startswith('.'):
+        sig = '.. %s::' % sig
+        signode += addnodes.desc_name(sig, sig)
+        return
+    m = dir_sig_re.match(sig)
+    if not m:
+        signode += addnodes.desc_name(sig, sig)
+        return
+    name, args = m.groups()
+    name = '.. %s::' % name
+    signode += addnodes.desc_name(name, name)
+    signode += addnodes.desc_classname(args, args)
+
+
+def parse_role(sig, signode):
+    signode += addnodes.desc_name(':%s:' % sig, ':%s:' % sig)
+
+
 def setup(app):
-    app.add_description_unit('directive', 'dir', 'directive')
-    app.add_description_unit('role', 'role', 'role')
+    app.add_description_unit('directive', 'dir', 'directive', parse_directive)
+    app.add_description_unit('role', 'role', 'role', parse_role)
     app.add_description_unit('confval', 'confval', 'configuration value')

doc/ext/api.rst

-Extension API
-=============
-
-Each Sphinx extension is a Python module with at least a :func:`setup` function.
-This function is called at initialization time with one argument, the
-application object representing the Sphinx process.  This application object has
-the following public API:
-
-.. method:: Application.add_builder(builder)
-
-   Register a new builder.  *builder* must be a class that inherits from
-   :class:`~sphinx.builder.Builder`.
-
-.. method:: Application.add_config_value(name, default, rebuild_env)
-
-   Register a configuration value.  This is necessary for Sphinx to recognize
-   new values and set default values accordingly.  The *name* should be prefixed
-   with the extension name, to avoid clashes.  The *default* value can be any
-   Python object.  The boolean value *rebuild_env* must be ``True`` if a change
-   in the setting only takes effect when a document is parsed -- this means that
-   the whole environment must be rebuilt.
-
-.. method:: Application.add_event(name)
-
-   Register an event called *name*.
-
-.. method:: Application.add_node(node)
-
-   Register a Docutils node class.  This is necessary for Docutils internals.
-   It may also be used in the future to validate nodes in the parsed documents.
-
-.. method:: Application.add_directive(name, cls, content, arguments, **options)
-
-   Register a Docutils directive.  *name* must be the prospective directive
-   name, *func* the directive function (see the Docutils documentation - XXX
-   ref) for details about the signature and return value.  *content*,
-   *arguments* and *options* are set as attributes on the function and determine
-   whether the directive has content, arguments and options, respectively.  For
-   their exact meaning, please consult the Docutils documentation.
-   
-.. method:: Application.add_role(name, role)
-
-   Register a Docutils role.  *name* must be the role name that occurs in the
-   source, *role* the role function (see the Docutils documentation on details).
-
-.. method:: Application.add_description_unit(directivename, rolename, indexdesc='', parse_node=None)
-
-   XXX
-
-.. method:: Application.connect(event, callback)
-
-   Register *callback* to be called when *event* is emitted.  For details on
-   available core events and the arguments of callback functions, please see
-   :ref:`events`.
-
-   The method returns a "listener ID" that can be used as an argument to
-   :meth:`disconnect`.
-
-.. method:: Application.disconnect(listener_id)
-
-   Unregister callback *listener_id*.
-
-.. method:: Application.emit(event, *arguments)
-
-   Emit *event* and pass *arguments* to the callback functions.  Do not emit
-   core Sphinx events in extensions!
-
-
-.. exception:: ExtensionError
-
-   All these functions raise this exception if something went wrong with the
-   extension API.
-
-Examples of using the Sphinx extension API can be seen in the :mod:`sphinx.ext`
-package.
-
-
-.. _events:
-
-Sphinx core events
-------------------
-
-These events are known to the core:
-
-====================== =================================== =========
-Event name             Emitted when                        Arguments
-====================== =================================== =========
-``'builder-inited'``   the builder object has been created -none-
-``'doctree-read'``     a doctree has been parsed and read  *doctree*
-                       by the environment, and is about to
-                       be pickled
-``'doctree-resolved'`` a doctree has been "resolved" by    *doctree*, *docname*
-                       the environment, that is, all
-                       references and TOCs have been
-                       inserted
-====================== =================================== =========

doc/ext/appapi.rst

+Extension API
+=============
+
+Each Sphinx extension is a Python module with at least a :func:`setup` function.
+This function is called at initialization time with one argument, the
+application object representing the Sphinx process.  This application object has
+the following public API:
+
+.. method:: Application.add_builder(builder)
+
+   Register a new builder.  *builder* must be a class that inherits from
+   :class:`~sphinx.builder.Builder`.
+
+.. method:: Application.add_config_value(name, default, rebuild_env)
+
+   Register a configuration value.  This is necessary for Sphinx to recognize
+   new values and set default values accordingly.  The *name* should be prefixed
+   with the extension name, to avoid clashes.  The *default* value can be any
+   Python object.  The boolean value *rebuild_env* must be ``True`` if a change
+   in the setting only takes effect when a document is parsed -- this means that
+   the whole environment must be rebuilt.
+
+.. method:: Application.add_event(name)
+
+   Register an event called *name*.
+
+.. method:: Application.add_node(node)
+
+   Register a Docutils node class.  This is necessary for Docutils internals.
+   It may also be used in the future to validate nodes in the parsed documents.
+
+.. method:: Application.add_directive(name, cls, content, arguments, **options)
+
+   Register a Docutils directive.  *name* must be the prospective directive
+   name, *func* the directive function (see the Docutils documentation - XXX
+   ref) for details about the signature and return value.  *content*,
+   *arguments* and *options* are set as attributes on the function and determine
+   whether the directive has content, arguments and options, respectively.  For
+   their exact meaning, please consult the Docutils documentation.
+   
+.. method:: Application.add_role(name, role)
+
+   Register a Docutils role.  *name* must be the role name that occurs in the
+   source, *role* the role function (see the Docutils documentation on details).
+
+.. method:: Application.add_description_unit(directivename, rolename, indexdesc='', parse_node=None)
+
+   XXX
+
+.. method:: Application.connect(event, callback)
+
+   Register *callback* to be called when *event* is emitted.  For details on
+   available core events and the arguments of callback functions, please see
+   :ref:`events`.
+
+   The method returns a "listener ID" that can be used as an argument to
+   :meth:`disconnect`.
+
+.. method:: Application.disconnect(listener_id)
+
+   Unregister callback *listener_id*.
+
+.. method:: Application.emit(event, *arguments)
+
+   Emit *event* and pass *arguments* to the callback functions.  Do not emit
+   core Sphinx events in extensions!
+
+
+.. exception:: ExtensionError
+
+   All these functions raise this exception if something went wrong with the
+   extension API.
+
+Examples of using the Sphinx extension API can be seen in the :mod:`sphinx.ext`
+package.
+
+
+.. _events:
+
+Sphinx core events
+------------------
+
+These events are known to the core:
+
+====================== =================================== =========
+Event name             Emitted when                        Arguments
+====================== =================================== =========
+``'builder-inited'``   the builder object has been created -none-
+``'doctree-read'``     a doctree has been parsed and read  *doctree*
+                       by the environment, and is about to
+                       be pickled
+``'doctree-resolved'`` a doctree has been "resolved" by    *doctree*, *docname*
+                       the environment, that is, all
+                       references and TOCs have been
+                       inserted
+====================== =================================== =========

doc/ext/builderapi.rst

+Writing new builders
+====================
+
+.. class:: sphinx.builder.Builder
+
+   This is the base class for all builders.
+
+   These methods are predefined and will be called from the application:
+
+   .. automethod:: load_env
+   .. automethod:: get_relative_uri
+   .. automethod:: build_all
+   .. automethod:: build_specific
+   .. automethod:: build_update
+   .. automethod:: build
+
+   These methods must be overridden in concrete builder classes:
+
+   .. automethod:: init
+   .. automethod:: get_outdated_docs
+   .. automethod:: get_target_uri
+   .. automethod:: prepare_writing
+   .. automethod:: write_doc
+   .. automethod:: finish

doc/extensions.rst

 
 .. toctree::
 
-   ext/api.rst
+   ext/appapi
+   ext/builderapi
 
 
 Builtin Sphinx extensions
 
 .. toctree::
 
-   ext/autodoc.rst
-   ext/doctest.rst
-   ext/refcounting.rst
-   ext/ifconfig.rst
-   ext/coverage.rst
+   ext/autodoc
+   ext/doctest
+   ext/refcounting
+   ext/ifconfig
+   ext/coverage
 
 and answer the questions.
 
-.. XXX environment
-
 
 Running a build
 ---------------

doc/markup/code.rst

 Showing code examples
 ---------------------
 
+.. index:: pair: code; examples
+           single: sourcecode
+
 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.
 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::
+.. directive:: .. literalinclude:: filename
 
-   .. literalinclude:: example.py
+   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::
 
-The file name is relative to the current file's path.
+      .. literalinclude:: example.py
+
+   The file name is relative to the current file's path.
+
+   The directive also supports the ``linenos`` flag option to switch on line
+   numbers, and a ``language`` option to select a language different from the
+   current file's standard language.  Example with options::
+    
+      .. literalinclude:: example.rb
+         :language: ruby
+         :linenos:
 
 
 .. rubric:: Footnotes

doc/markup/desc.rst

+.. 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@python.invalid>
+   .. moduleauthor:: John Idle <john@python.invalid>
+
+As you can see, the module-specific markup consists of two directives, the
+``module`` directive and the ``moduleauthor`` directive.
+
+.. directive:: .. module:: name
+
+   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:: name <email>
+
+   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.
+
+
+Description 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:: type name(signature)
+
+   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:: type name
+
+   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:: name
+
+   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:: name
+
+   Describes a C type. The signature should just be the type name.
+
+.. directive:: .. cvar:: type name
+
+   Describes a global C variable.  The signature should include the type, such
+   as::
+
+      .. cvar:: PyObject* PyClass_Type
+
+.. directive:: .. data:: name
+
+   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:: name
+
+   Describes an exception class.  The signature can, but need not include
+   parentheses with constructor arguments.
+
+.. directive:: .. function:: name(signature)
+
+   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:: name[(signature)]
+
+   Describes a class.  The signature can include parentheses with parameters
+   which will be shown as the constructor arguments.
+
+.. directive:: .. attribute:: name
+
+   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:: name(signature)
+
+   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:: name
+
+   Describes a Python bytecode instruction (this is not very useful for projects
+   other than Python itself).
+
+.. directive:: .. cmdoption:: name args
+
+   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:: name
+
+   Describes an environment variable that the documented code uses or defines.
+
+
+There is also a generic version of these directives:
+
+.. directive:: .. describe:: text
+
+   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.

doc/markup/index.rst

-.. XXX missing: glossary
-
 Sphinx Markup Constructs
 ========================
 
 
 .. toctree::
 
-   infounits.rst
-   para.rst
-   code.rst
-   inline.rst
-   misc.rst
+   desc
+   para
+   code
+   inline
+   misc

doc/markup/infounits.rst

-.. 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@python.invalid>
-   .. moduleauthor:: John Idle <john@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.

doc/markup/inline.rst

 .. highlight:: rest
 
 Inline markup
--------------
+=============
 
-As said before, Sphinx uses interpreted text roles to insert semantic markup in
-documents.
+Sphinx uses interpreted text roles to insert semantic markup into documents.
 
 Variable names are an exception, they should be marked simply with ``*var*``.
 
 
 .. note::
 
-   For all cross-referencing roles, if you prefix the content with ``!``, no
-   reference/hyperlink will be created.
+   The default role (```content```) has no special meaning by default.  You are
+   free to use it for anything you like. 
+
+
+Cross-referencing syntax
+------------------------
+
+Cross-references are generated by many semantic interpreted text roles.
+Basically, you only need to write ``:role:`target```, and a link will be created
+to the item named *target* of the type indicated by *role*.  The links's text
+will be the same as *target*.
+
+There are some additional facilities, however, 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.
+
+
+Cross-referencing Python objects
+--------------------------------
 
 The following roles refer to objects in modules and are possibly hyperlinked if
 a matching identifier is found:
 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
+dot, this order is reversed.  For example, in the documentation of Python's
 :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.
 
+
+Cross-referencing C constructs
+------------------------------
+
 The following roles create cross-references to C-language constructs if they
-are defined in the API documentation:
+are defined in the documentation:
 
 .. role:: cdata
 
    The name of a C-language type.
 
 
-The following roles do possibly create a cross-reference, but do not refer
-to objects:
+Cross-referencing other items of interest
+-----------------------------------------
+
+The following roles do possibly create a cross-reference, but do not refer to
+objects:
+
+.. role:: envvar
+
+   An environment variable.  Index entries are generated.  Also generates a link
+   to the matching :dir:`envvar` directive, if it exists.
 
 .. role:: token
 
-   The name of a grammar token (used in the reference manual to create links
-   between production displays).
+   The name of a grammar token (used to create links between
+   :dir:`productionlist` directives).
 
 .. role:: keyword
 
    The name of a keyword in Python.  This creates a link to a reference label
    with that name, if it exists.
 
+.. role:: option
+
+   A command-line option to an executable program.  The leading hyphen(s) must
+   be included.  This generates a link to a :dir:`cmdoption` directive, if it
+   exists.
+
 
 The following role creates a cross-reference to the term in the glossary:
 
    If you use a term that's not explained in a glossary, you'll get a warning
    during build.
 
----------
+
+Cross-referencing arbitrary locations
+-------------------------------------
+
+To support cross-referencing to arbitrary locations 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>```.
+
+
+Other semantic markup
+---------------------
 
 The following roles don't do anything special except formatting the text
 in a different style:
    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
 
    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
    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:
 
    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>```.

doc/markup/para.rst

 Paragraph-level markup
 ----------------------
 
+.. index:: note, warning
+           pair: changes; in version
+
 These directives create short paragraphs and can be used inside information
 units as well as normal text:
 
    appropriate punctuation. This differs from ``note`` in that it is recommended
    over ``note`` for information regarding security.
 
-.. directive:: versionadded
+.. directive:: .. versionadded:: version
 
    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
    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
+.. directive:: .. versionchanged:: version
 
    Similar to ``versionadded``, but describes when and what changed in the named
    feature in some way (new parameters, changed side effects, etc.).
          `GNU tar manual, Basic Tar Format <http://link>`_
             Documentation for tar archive files, including GNU tar extensions.
 
-.. directive:: rubric
+.. directive:: .. rubric:: title
 
    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.
 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.
+.. directive:: .. index:: <entries>
 
-For example::
+   This directive contains one or more index entries.  Each entry consists of a
+   type and a value, separated by a colon.
 
-   .. index::
-      single: execution; context
-      module: __main__
-      module: sys
-      triple: module; search; path
+   For example::
 
-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).
+      .. index::
+         single: execution; context
+         module: __main__
+         module: sys
+         triple: module; search; path
 
-The possible entry types are:
+   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).
 
-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``.
+   The possible entry types are:
 
-For index directives containing only "single" entries, there is a shorthand
-notation::
+   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``.
 
-   .. index:: BNF, grammar, syntax, notation
+   For index directives containing only "single" entries, there is a shorthand
+   notation::
 
-This creates four index entries.
+      .. index:: BNF, grammar, syntax, notation
+
+   This creates four index entries.
+
+
+Glossary
+--------
+
+.. directive:: glossary
+
+   This directive must contain a reST definition list with terms and
+   definitions.  The definitions will then be referencable with the :role:`term`
+   role.  Example::
+
+      .. glossary::
+
+         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.
+
 
 
 Grammar production displays
    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::
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.