Charles Poli, PhD

Head of Artificial Intelligence,
Cambridge Quantum Computing Limited, London.

Sphinx is a Python documentation generator, it allows to create html and latex documentations of python projects.
Visit the website http://sphinx-doc.org/.

Installation


To install Sphinx:

for Mac:
  launch a Terminal and
  • sudo port install pyXX-sphinx
for Ubuntu:
  launch a Terminal and
  • apt-get install python-sphinx
for Debian:
  launch a Terminal and
  • yum install python-sphinx
for Windows:
  launch a PowerShell Terminal and
  • pip install python-sphinx

A simple example


Create a directory

  • mkdir project
  • cd project

Create a Python file (let's call it proj.py)

'''
.. todo::

    Add a modulus_squared function.
'''

import math


def sum_diff(a, b):
    '''
    Calculate the sum and the difference of two variables.

    :param a: number
    :param b: number

    :return sum: sum of *a* and *b*
    :return diff: difference between *a* and *b*

    ::

        # Examples
        sum(1, 3) # output 4, -2
        sum(1+1j, -1j) # output 1, 1+2j
    '''
    sum = a + b
    diff = a - b
    return sum, diff


def modulus(z):
    r'''
    Calculate the modulus :math:`|z|` of a complex number :math:`z`.
    The modulus is given by:

    .. math::

        |z| = \sqrt{[\Re(z)]^2+[\Im(z)]^2}

    :param z: complex number

    :return modulus: modulus of :math:`z`
    '''
    modulus = math.sqrt(z.real**2 + z.imag**2)
    return modulus

Syntax


Sphinx is indent and line sensitive.

3 important Sphinx blocks:
.. todo::

     Things to be done.
.. note::

     Some notes.
::

     # python code
    

Math


math expressions:
In the text :math:`x+y`, like $x+y$ in latex
.. math::

     x+y

like $$x+y$$ in latex

Create the documentation

  • sphinx-apidoc -F -o path_doc/doc path_project/project
path_doc is the path of the parent directory which will contain the documentations

doc is the name of folder in which the documentations will be generated

path_project is the path of the parent directory of the project directory

project is the name of the directory containing the Python files to be documented

If you want doc and project to have the same parent directory run:
  • sphinx-apidoc -F -o doc project
Go to the doc directory and open conf.py

line 23
Define the path to the Python project.
If doc and project belong to the same parent directory:
sys.path.insert(0, os.path.abspath('../project'))

line 37
Add 'sphinx.ext.pngmath', (if you use latex expressions)

line xx
If you want the preserve the source ordering (alphabetic ordering otherwise)
copy paste
autodoc_member_order = 'bysource'

line 52
Change the name of the index if you have multiple docs
(1 index.html per website).
master_doc = 'index_proj'
And, change the name of index.rst accordingly (to index_proj.rst)
line 65
define the version of the project.
version = '0.1'

line 56 and 57
Add your name

line 106
Change the html theme
visit http://sphinx-doc.org/theming.html to pick up one.

line 218 (latex)
Change the font size
'pointsize': '12pt',

line 232 (latex)
Add your name


Using the terminal, go in the doc directory, if you want a html documentation, run
  • make html
if you want a latex documentation, run
  • make pdflatex
From the doc directory go to _build/html and/or _build/latex,
you will find the html/latex documentation files.


The html folder contains 4 html files:
index.html
proj.html
genindex.html
py-modindex.html

A bit of polishing

Let's make some changes in the index_proj.rst: Remove lines 16 to 22 (we don't need those for that example). line 14 change 'proj' to 'code' line 15 add 'about' (just below 'code') line 16 add 'examples' (just below 'code') line 9 remove 'Contents:' line 6 change the title to 'The Very Simple Example' line 12 Replace :maxdepth: 4' by :hidden: rename proj.rst to code.rst, create about.rst, create examples.rst ================

Done!


It is also possible to create .rst files and add them to the The proj.html looks like proj.html (with a bizstyle)

If you post the html doc on github
create an empty file name touch .nojekyll
    touch .nojekyll