Examples¶
Once Sphinx is installed, you can proceed with setting up your first Sphinx project. To ease the process of getting started, Sphinx provides a tool, sphinx-quickstart, which will generate a documentation source directory and populate it with some defaults. We’re going to use the sphinx-quickstart tool here, though it’s use by no means necessary.
Setting up the documentation sources¶
The root directory of a Sphinx collection of reStructuredText document
sources is called the source directory. This directory also contains
the Sphinx configuration file conf.py
, where you can configure all
aspects of how Sphinx reads your sources and builds your documentation. [#]_
Sphinx comes with a script called sphinx-quickstart that sets up a
source directory and creates a default conf.py
with the most useful
configuration values from a few questions it asks you. To use this, run:
$ sphinx-quickstart
Answer each question asked. Be sure to say yes to the autodoc
extension, as
we will use this later.
There is also an automatic “API documentation” generator called sphinx-apidoc; see /man/sphinx-apidoc for details.
Defining document structure¶
Let’s assume you’ve run sphinx-quickstart. It created a source
directory with conf.py
and a master document, index.rst
(if you
accepted the defaults). The main function of the master document is to
serve as a welcome page, and to contain the root of the “table of contents
tree” (or toctree). This is one of the main things that Sphinx adds to
reStructuredText, a way to connect multiple files to a single hierarchy of
documents.
The toctree
directive initially is empty, and looks like so:
.. toctree::
:maxdepth: 2
You add documents listing them in the content of the directive:
.. toctree::
:maxdepth: 2
usage/installation
usage/quickstart
...
This is exactly how the toctree
for this documentation looks. The
documents to include are given as document names, which in short
means that you leave off the file name extension and use forward slashes
(/
) as directory separators.
|more| Read more about the toctree directive.
You can now create the files you listed in the toctree
and add content, and
their section titles will be inserted (up to the maxdepth
level) at the
place where the toctree
directive is placed. Also, Sphinx now knows about
the order and hierarchy of your documents. (They may contain toctree
directives themselves, which means you can create deeply nested hierarchies if
necessary.)
Adding content¶
In Sphinx source files, you can use most features of standard
reStructuredText. There are also several features added by Sphinx.
For example, you can add cross-file references in a portable way (which works
for all output types) using the ref
role.
For an example, if you are viewing the HTML version you can look at the source for this document – use the “Show Source” link in the sidebar.
|more| See /usage/restructuredtext/index for a more in-depth introduction to reStructuredText, including markup added by Sphinx.