5. Building that Documentation

The objective is to have an easily maintainable and yet simple and powerful documentation. For all these reasons we chose Sphinx. Sphinx has many benefits :

  • A simple syntax (rST)
  • Provides a simple navigation
  • Manages source code blocks
  • Manages source code doc comments
  • Manages images
  • Manages mathematics
  • Manages LaTeX compilation

You will find an introduction to rST syntax here : http://sphinx-doc.org/rest.html

5.1. Sphinx Installation

You can find all the details here : http://sphinx-doc.org/install.html. The simplest way is to use Python package manager (pip) :

$ sudo pip install sphinx

Attention

If you use some Ubuntu derived distribution, you might need to use pip3 instead of pip.

5.2. Initialize the documentation

Sources of the documentation will reside in the docs folder. Use the sphinx-quickstart command to start the documentation :

$ mkdir docs
$ cd docs/
$ sphinx-quickstart

The default configuration is almost OK but we need to change some answers :

> Separate source and build directories (y/n) [n]: y
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y

At the end of the script, Sphinx configuration has been initialized. It has setup 2 folders : build and source. It also created a Makefile allowing to easily build the doc with commands such as :

$ make html

5.3. Configuration of Sphinx documentation

The sphinx-quickstart script generated files allowing us to configure Sphinx. Here are some additional information to setup your documentation.

5.3.1. Host your documentation on Github

If you have a Github repository you can host your documentation on the Github pages of your repository. See https://help.github.com/articles/what-are-github-pages/ for more explanations on it.

To activate the Github pages of your repository you only have to create a new branch called gh-pages and to push it on origin.

$ git checkout --orphan gh-pages
$ git rm -rf .
$ echo "My page" > index.html
$ git add index.html
$ git commit -am "Premier commit sur les pages Github"
$ git push origin gh-pages -u

5.3.2. Configure HTML build

In practice we need to build into the gh-pages branch. But it is not immediately possible since we are not gh-pages branch when compiling.

The easiest solution according to me is to have 2 folders. One with the standard repository, and the other one with only the gh-pages branch (so it is lightweight) of the same repository. Then you only have to configure your Sphinx build so that it builds into the folder containing the repository on the gh-pages branch.

Example for creating the second folder :

$ pwd
/home/......../MATRIX
$ cd ../
$ mkdir MATRIX_gh-pages
$ cd MATRIX_gh-pages/
$ git clone -b gh-pages --single-branch git@github.com:mpizenberg/MATRIX.git .

Now we just need to modify the make file MATRIX/docs/Makefile :

BUILDDIR = ../../MATRIX_gh-pages

html:
   $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)

5.3.3. Use the theme rTD (readTheDocs)

You only need to install the theme with pip.

$ sudo pip install sphinx_rtd_theme

Then in the file conf.py :

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Once it is installed, there is one last manipulation. You have to add an empty file entitled .nojekyll in the gh-pages branch. Otherwise Github will ignore folders starting with _. It would be a problem since the folder _static contains CSS styles and images needed for the theme.