diff --git a/doc/builders.rst b/doc/builders.rst index ee28a1b4b..6ba2147ce 100644 --- a/doc/builders.rst +++ b/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 + 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. diff --git a/doc/extensions.rst b/doc/extensions.rst index 1bb52c4b5..1aa9aa169 100644 --- a/doc/extensions.rst +++ b/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. -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: +.. toctree:: -.. 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! + ext/api.rst -.. exception:: ExtensionError +Builtin Sphinx extensions +------------------------- - All these functions raise this exception if something went wrong with the - extension API. +These extensions are built in and can be activated by respective entries in the +:confval:`extensions` configuration value: -Examples of using the Sphinx extension API can be seen in the :mod:`sphinx.ext` -package. +.. toctree:: - -.. _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 -====================== =================================== ========= + ext/autodoc.rst + ext/doctest.rst + ext/refcounting.rst + ext/ifconfig.rst + ext/coverage.rst diff --git a/doc/intro.rst b/doc/intro.rst index bf56c8c13..1d6941353 100644 --- a/doc/intro.rst +++ b/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). diff --git a/doc/templating.rst b/doc/templating.rst index eb3a3bf6c..2519d7177 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -2,3 +2,61 @@ Templating ========== + +Sphinx uses the `Jinja ` 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 ```` 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 ``