Some more documentation.

doc/builders.rst

@@ -7,3 +7,17 @@ Builders and the environment
    :synopsis: Available built-in builder classes.
 
 
+.. class:: Builder
+
+.. class:: StandaloneHTMLBuilder
+
+.. class:: WebHTMLBuilder
+
+.. class:: HTMLHelpBuilder
+
+.. class:: LaTeXBuilder
+
+.. class:: ChangesBuilder
+
+.. class:: CheckExternalLinksBuilder
+

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
+====================== =================================== =========

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.

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

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.

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.

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.

doc/extensions.rst

@@ -15,96 +15,21 @@ 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.
+.. toctree::
-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)
+   ext/api.rst
-
-   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
+Builtin Sphinx extensions
+-------------------------
 
-   All these functions raise this exception if something went wrong with the
+These extensions are built in and can be activated by respective entries in the
-   extension API.
+:confval:`extensions` configuration value:
 
-Examples of using the Sphinx extension API can be seen in the :mod:`sphinx.ext`
+.. toctree::
-package.
 
-
+   ext/autodoc.rst
-.. _events:
+   ext/doctest.rst
-
+   ext/refcounting.rst
-Sphinx core events
+   ext/ifconfig.rst
-------------------
+   ext/coverage.rst
-
-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/intro.rst

@@ -1,11 +1,90 @@
 Introduction
 ============
 
+This is the documentation for the Sphinx documentation builder.  Sphinx is a
+tool that translates a set of reStructuredText_ source files into various output
+formats, automatically producing cross-references, indices etc.
 
+.. XXX web app
 
 Prerequisites
 -------------
 
+Sphinx needs at least **Python 2.4** to run.  If you like to have source code
+highlighting support, you must also install the Pygments_ library, which you can
+do via setuptools' easy_install.
+
+.. _reStructuredText: http://docutils.sf.net/rst.html
+.. _Pygments: http://pygments.org
+
+
+Setting up a documentation root
+-------------------------------
+
+The root directory of a documentation collection is called the
+:dfn:`documentation root`.  There's nothing special about it; it just needs to
+contain the Sphinx configuration file, :file:`conf.py`.
+
+Sphinx comes with a script called :program:`sphinx-quickstart.py` that sets up a
+documentation root and creates a default :file:`conf.py` from a few questions
+it asks you.  Just run ::
+
+   $ sphinx-quickstart.py
+
+and answer the questions.
+
+.. XXX environment
+
 
 Running a build
 ---------------
+
+A build is started with the :program:`sphinx-build.py` script.  It is called
+like this::
+
+     $ sphinx-build.py -b latex sourcedir builddir
+
+where *sourcedir* is the :term:`documentation root`, and *builddir* is the
+directory in which you want to place the built documentation (it must be an
+existing directory).  The :option:`-b` option selects a builder; in this example
+Sphinx will build LaTeX files.
+
+The :program:`sphinx-build.py` script has several more options:
+
+**-a**
+   If given, always write all output files.  The default is to only write output
+   files for new and changed source files.  (This may not apply to all
+   builders.)
+
+**-E**
+   Don't use a saved :term:`environment` (the structure caching all
+   cross-references), but rebuild it completely.  The default is to only read
+   and parse source files that are new or have changed since the last run.
+
+**-d** *path*
+   Since Sphinx has to read and parse all source files before it can write an
+   output file, the parsed source files are cached as "doctree pickles".
+   Normally, these files are put in a directory called :file:`.doctrees` under
+   the build directory; with this option you can select a different cache
+   directory (the doctrees can be shared between all builders).
+
+**-D** *setting=value*
+   Override a configuration value set in the :file:`conf.py` file.  (The value
+   must be a string value.)
+
+**-N**
+   Do not do colored output.  (On Windows, colored output is disabled in any
+   case.)
+
+**-q**
+   Do not output anything on standard output, only write warnings to standard
+   error.
+
+**-P**
+   (Useful for debugging only.)  Run the Python debugger, :mod:`pdb`, if an
+   unhandled exception occurs while building.
+
+
+You can also give one or more filenames on the command line after the source and
+build directories.  Sphinx will then try to build only these output files (and
+their dependencies).

doc/templating.rst

@@ -2,3 +2,61 @@
 
 Templating
 ==========
+
+Sphinx uses the `Jinja <http://jinja.pocoo.org>` templating engine for its HTML
+templates.  Jinja is a text-based engine, and inspired by Django templates, so
+anyone having used Django will already be familiar with it.  It also has
+excellent documentation for those who need to make themselves familiar with it.
+
+The most important concept in Jinja is :dfn:`template inheritance`, which means
+that you can overwrite only specific blocks within a template, customizing it
+while also keeping the changes at a minimum.
+
+Inheritance is done via two directives, ``extends`` and ``block``.
+
+.. template path
+   blocks
+   extends !template
+
+These are the blocks that are predefined in Sphinx' ``layout.html`` template:
+
+**doctype**
+   The doctype, by default HTML 4 Transitional.
+
+**rellinks**
+   HTML ``<link rel=`` links in the head, by default filled with various links.
+
+**extrahead**
+   Block in the ``<head>`` tag, by default empty.
+
+**beforerelbar**
+   Block before the "related bar" (the navigation links at the page top), by
+   default empty.  Use this to insert a page header.
+
+**relbar**
+   The "related bar" by default.  Overwrite this block to customize the entire
+   navigation bar.
+
+**rootrellink**
+   The most parent relbar link, by default pointing to the "index" document with
+   a caption of e.g. "Project v0.1 documentation".
+
+**relbaritems**
+   Block in the ``<ul>`` used for relbar items, by default empty.  Use this to
+   add more items.
+
+**afterrelbar**
+   Block between relbar and document body, by default empty.
+
+**body**
+   Block in the document body.  This should be overwritten by every child
+   template, e.g. :file:`page.html` puts the page content there.
+
+**beforesidebar**
+   Block between body and sidebar, by default empty.
+
+**sidebar**
+   Contains the whole sidebar.
+
+**aftersidebar**
+   Block between