sphinx / doc / intro.rst

Full commit


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.

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.


While Sphinx' version is still 0.1.revision, no mention will be made in the docs if a feature is added or changed. The :ref:`Changelog <changes>` is the only source of version annotations.


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.

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:``.

Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a documentation root and creates a default :file:`` from a few questions it asks you. Just run

$ sphinx-quickstart

and answer the questions.

Running a build

A build is started with the :program:`sphinx-build` script. It is called like this:

$ sphinx-build -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` script has several more options:

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.)
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:`` file. (The value must be a string value.)
Do not do colored output. (On Windows, colored output is disabled in any case.)
Do not output anything on standard output, only write warnings to standard error.
(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).