Some more documentation.

6 files changed, 161 insertions, 0 deletions

diff --git a/doc/ext/api.rst b/doc/ext/api.rst
new file mode 100644
index 000000000..5d56850f4
--- /dev/null
+++ b/doc/ext/api.rst
@@ -0,0 +1,96 @@
+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
+====================== =================================== =========
diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
new file mode 100644
index 000000000..6ab4345d4
--- /dev/null
+++ b/doc/ext/autodoc.rst
@@ -0,0 +1,5 @@
+:mod:`sphinx.ext.autodoc` -- Include documentation from docstrings
+==================================================================
+
+.. module:: sphinx.ext.autodoc
+   :synopsis: Include documentation from docstrings.
diff --git a/doc/ext/coverage.rst b/doc/ext/coverage.rst
new file mode 100644
index 000000000..d16a7e20d
--- /dev/null
+++ b/doc/ext/coverage.rst
@@ -0,0 +1,29 @@
+:mod:`sphinx.ext.coverage` -- Collect doc coverage stats
+========================================================
+
+.. module:: sphinx.ext.coverage
+   :synopsis: Check Python modules and C API for coverage in the documentation.
+
+
+This extension features one additional builder, the :class:`CoverageBuilder`.
+
+.. class:: CoverageBuilder
+
+   To use this builder, activate the coverage extension in your configuration
+   file and give ``-b coverage`` on the command line.
+
+
+Several new configuration values can be used to specify what the builder
+should check:
+
+.. confval:: coverage_ignore_modules
+
+.. confval:: coverage_ignore_functions
+
+.. confval:: coverage_ignore_classes
+
+.. confval:: coverage_c_path
+
+.. confval:: coverage_c_regexes
+
+.. confval:: coverage_ignore_c_items
diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst
new file mode 100644
index 000000000..2657ad77a
--- /dev/null
+++ b/doc/ext/doctest.rst
@@ -0,0 +1,5 @@
+:mod:`sphinx.ext.doctest` -- Test snippets in the documentation
+===============================================================
+
+.. module:: sphinx.ext.doctest
+   :synopsis: Test snippets in the documentation.
diff --git a/doc/ext/ifconfig.rst b/doc/ext/ifconfig.rst
new file mode 100644
index 000000000..f75f566bd
--- /dev/null
+++ b/doc/ext/ifconfig.rst
@@ -0,0 +1,21 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.ifconfig` -- Include content based on configuration
+====================================================================
+
+.. module:: sphinx.ext.ifconfig
+   :synopsis: Include documentation content based on configuration values.
+
+This extension is quite simple, and features only one directive:
+
+.. directive:: ifconfig
+
+   Include content of the directive only if the Python expression given as an
+   argument is ``True``, evaluated in the namespace of the project's
+   configuration (that is, all variables from :file:`conf.py` are available).
+
+   For example, one could write ::
+
+      .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
+
+         This stuff is only included in the built docs for unstable versions.
diff --git a/doc/ext/refcounting.rst b/doc/ext/refcounting.rst
new file mode 100644
index 000000000..e771e1aa2
--- /dev/null
+++ b/doc/ext/refcounting.rst
@@ -0,0 +1,5 @@
+:mod:`sphinx.ext.refcounting` -- Keep track of reference counting behavior
+==========================================================================
+
+.. module:: sphinx.ext.refcounting
+   :synopsis: Keep track of reference counting behavior.