Boson Editor

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.

reStructuredText directives

toctree is a reStructuredText directive, a very versatile piece of markup. Directives can have arguments, options and content.

Arguments are given directly after the double colon following the directive’s name. Each directive decides whether it can have arguments, and how many.

Options are given after the arguments, in form of a “field list”. The maxdepth is such an option for the toctree directive.

Content follows the options or arguments after a blank line. Each directive decides whether to allow content, and what to do with it.

A common gotcha with directives is that the first line of the content must be indented to the same level as the options are.

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.