Sphinx in short

Brief view of the steps to set up Sphinx for your project:

1. Open a terminal and go to the project directory.

2. Launch sphinx-quickstart

   $ sphinx-quickstart
   

3. Open docs/source/conf.py to make the following changes:

   1. Set the path to the code:

      sys.path.insert(0, os.path.abspath('../..'))
      

   2. Add napoleon to the extensions list 1:

      extensions = [..., 'sphinx.ext.napoleon']
      

   3. Import version from the project:

      import <project name>
      version = <project name>.__version__
      release = <project name>.__version__
      

   4. Change the HTML theme:

      html_theme = 'sphinx_rtd_theme'
      

4. Create your docs and add them to the toctree:

   .. toctree::
      :maxdepth: 2
   
      intro
      tutorial
      ...
   

5. Generate API docs

   1. Create the files to automatically load the docstrings and generate the corresponding docs:

      $ sphinx-apidoc -f -o docs/source/pkg . test setup.py
      

   2. Add the docs/source/pkg/modules.rst file to a toctree.

6. Build your docs:

   $ make html
   

1

The napoleon extension in needed to use Google or Numpy docstring. Skip this step if you are using reStructuredText format for the docstrings.