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. That is, if you have a directory containing a bunch of reST-formatted documents (and possibly subdirectories of docs in there as well), Sphinx can generate a nicely-organized arrangement of HTML files (in some other directory) for easy browsing and navigation. But from the same source, it can also generate a LaTeX file that you can compile into a PDF version of the documents.
The focus is on hand-written documentation, rather than auto-generated API docs. Though there is limited support for that kind of docs as well (which is intended to be freely mixed with hand-written content), if you need pure API docs have a look at Epydoc, which also understands reST.
This section is intended to collect helpful hints for those wanting to migrate to reStructuredText/Sphinx from other documentation systems.
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. Sphinx should work with docutils version 0.4 or some (not broken) SVN trunk snapshot.
The root directory of a documentation collection is called the source directory. Normally, this directory also contains the Sphinx configuration file conf.py, but that file can also live in another directory, the configuration directory.
New in version 0.3: Support for a different configuration directory.
Sphinx comes with a script called sphinx-quickstart that sets up a source directory and creates a default conf.py from a few questions it asks you. Just run
$ sphinx-quickstart
and answer the questions.
A build is started with the sphinx-build script. It is called like this:
$ sphinx-build -b latex sourcedir builddir
where sourcedir is the source directory, and builddir is the directory in which you want to place the built documentation (it must be an existing directory). The -b option selects a builder; in this example Sphinx will build LaTeX files.
The sphinx-build script has several more options:
Define the tag tag. This is relevant for only directives that only include their content if this tag is set.
New in version 0.6.
Don’t look for the conf.py in the source directory, but use the given configuration directory instead. Note that various other files and paths given by configuration values are expected to be relative to the configuration directory, so they will have to be present at this location too.
New in version 0.3.
Don’t look for a configuration file; only take options via the -D option.
New in version 0.5.
Override a configuration value set in the conf.py file. The value must be a string or dictionary value. For the latter, supply the setting name and key like this: -D latex_elements.docclass=scrartcl.
Changed in version 0.6: The value can now be a dictionary value.
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).