First pass at Sphinx documentation. Most of it still needs to be written :)

1 files changed, 110 insertions, 0 deletions

diff --git a/doc/extensions.rst b/doc/extensions.rst
new file mode 100644
index 00000000..1bb52c4b
--- /dev/null
+++ b/doc/extensions.rst
@@ -0,0 +1,110 @@
+.. _extensions:
+
+Sphinx Extensions
+=================
+
+.. module:: sphinx.application
+   :synopsis: Application class and extensibility interface.
+
+Since many projects will need special features in their documentation, Sphinx is
+designed to be extensible on several levels.
+
+First, you can add new :term:`builder`\s to support new output formats or
+actions on the parsed documents.  Then, it is possible to register custom
+reStructuredText roles and directives, extending the markup.  And finally, there
+are so-called "hook points" at strategic places throughout the build process,
+where an extension can register a hook and run specialized code.
+
+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
+====================== =================================== =========