Getting started

Starting Sphinx

One of the easiest way to start Sphinx is using the quickstart. It will create the basic files you need to be able to generate the documentation.

To use the quickstart follow these steps:

  1. Open a terminal, go to the project directory and create a docs folder:

    $ cd path/to/project
$ mkdir docs

  2. Launch sphinx-quickstart:

    $ cd docs
$ sphinx-quickstart

    Sphinx asks you how to set up the initial configuration. It is recommended to separate source and build directories.

    Note

    Sphinx 1.X will make quite more questions than 2.X versions in order to decided which extensions to load (that are loaded by default in 2.X version).

    After you answer all the questions, Sphinx will create some files for you like a conf.py, a Makefile and a main .rst (named index by default).

The setup

After setting up your docs folder, the project structure should be similar to (note that the project directory is collapsed):

project/
|
|-- docs/
|   |-- build/
|   |-- source/
|   |   |-- _templates
|   |   |-- _static
|   |   |-- index.rst
|   |   |-- conf.py
|   |-- Makefile
|
|-- project/
|
|-- README.rst
|-- setup.py

The source folder is intended to contain the .rst files or any other files related to the documentations. It can also include templates or other static files used during the build process.

The Makefile is a script for building the documentations. The usage is:

make <output format>

E.g.:

make html

index.rst is the masterdoc. Its function is to serve as welcome page and to contain the root of the toctree. All .rst files in the source directory are compiled, but only the ones explicitly set in a toctree are shown 1.

The easiest way to include a new .rst file is to add it to the source folder and put its name (with or without extension) in the toctree of the masterdoc:

.. toctree::
   :maxdepth: 2

   intro
   tutorial
   ...

The conf.py is the file where the configuration for the build process can be modified.

1

Nested documents can include their own toctrees. Documents not mention in any toctree are still accessible through the search bar in the html output.