mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Some more documentation.
This commit is contained in:
Georg Brandl
parent
19df48d2cb
commit
6d7d1f6e50
@ -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
|
||||
|
||||
|
||||
96
doc/ext/api.rst
Normal file
96
doc/ext/api.rst
Normal file
@ -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
|
||||
====================== =================================== =========
|
||||
5
doc/ext/autodoc.rst
Normal file
5
doc/ext/autodoc.rst
Normal file
@ -0,0 +1,5 @@
|
||||
:mod:`sphinx.ext.autodoc` -- Include documentation from docstrings
|
||||
==================================================================
|
||||
|
||||
.. module:: sphinx.ext.autodoc
|
||||
:synopsis: Include documentation from docstrings.
|
||||
29
doc/ext/coverage.rst
Normal file
29
doc/ext/coverage.rst
Normal file
@ -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
|
||||
5
doc/ext/doctest.rst
Normal file
5
doc/ext/doctest.rst
Normal file
@ -0,0 +1,5 @@
|
||||
:mod:`sphinx.ext.doctest` -- Test snippets in the documentation
|
||||
===============================================================
|
||||
|
||||
.. module:: sphinx.ext.doctest
|
||||
:synopsis: Test snippets in the documentation.
|
||||
21
doc/ext/ifconfig.rst
Normal file
21
doc/ext/ifconfig.rst
Normal file
@ -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.
|
||||
5
doc/ext/refcounting.rst
Normal file
5
doc/ext/refcounting.rst
Normal file
@ -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.
|
||||
@ -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
|
||||
|
||||
@ -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).
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user