How to use Sphinx Documentation

Write and preview with VSCode

The following method allows you to write and preview the doc easily thanks to VSCode.
For the older system (less direct for the preview, but with more log), see Sphinx Requirements.

Requirements

You need to install :

  • Python <- on the first installer’s page, select the checkbox to add it to PATH

  • Git - you can use a graphical interface to, among others, see the previous commits

    • Fork is a simple client for Mac and Windows

    • Kraken is another client for Mac, Windows and Linux

  • Visual Studio Code

    • You need to enable the dark theme, because else you will not be a real new-gen developer !

Prepare environment

Open your Git client and clone the doc repository. It may take some time to clone.
Open a prompt and run :
python install pip
pip install pipenv
The install command will take some time.
Go to the spl-docs folder, and edit the Pipfile with any text editor.
Modify the python_version to yours (it has been tested with Python 3.7, 3.8 and 3.9) :
[requires]
python_version = "3.9"

Note

If you do not remember your version, you can type where python from your prompt and the resulting path will certainly contain the version number.

Inside the spl-docs folder, run :

pipenv install

Finally, open VSCode and install the following extensions :

  • Python

  • reStructuredText (the one with a big version number, with the parchment as picture)

The environment is ready !

Write and preview

Open the spl-docs folder within VSCode (you can then create a workspace to quickly re-open it later).
Do Ctrl + Maj + P and type Python : Select Interpreter, and select the correct pipenv environment :
../_images/sphinx_pipenv.png
Open any .rst file. You can now do Ctrl + Maj + P and type reStructuredText : Open Preview.
Three pop-ups will show up. Install all (it will install Jupyter and Pylance extensions along with other required tools) :
../_images/sphinx_exts.png

Note

If you relaunch the command, you may encounter an error. Try to restart VSCode.
If it does not help, go to the reStructuredText plugin settings and set ConfPath to ${workspaceFolder}/source (and maybe restart VSCode once again).
The first preview launch takes a bit of time (it will build the doc, but then the page you currently are on will be displayed.
To update the preview, simply save your file and, some seconds after, the view will be refreshed.
The main problem is, if you have your preview on a second column near your .rst file, that it will jump :
  • On each refresh

  • If you move the preview scrolling bar instead of moving the .rst scrolling bar (it will reset the .rst file to its beginning)

  • Sometimes while you write, if you are past the area where no scroll is needed on the preview

../_images/sphinx_preview.gif

The preview will likely match the final online result !

Important

Unlike pipenv make html, you will not get any feedback on non-fatal errors hidden in your syntax.

Finally, push your changes through Git.
Do not push the _build folder, nor any other modification (e.g. .workspace file, .vscode folder …) other than the the files you modified and the pictures and files you added.

Sphinx Requirements

In order to fully build a sphinx documentation with all different outputs, the following programs must be installed:

Sphinx programs requirements

Description

Python

Python interpreter

Make

Build tool

Graphviz

Optional, to generate image from dot language

Pandoc

Optional, to convert markdown to reStructuredText

Latex Tools

Optional, for latex build

Inkscape

Optional, for .svg to .pdf and to .png conversion

Java

Optional, for Plantuml images

Important

Optional programs are only required if you plan to write a page using syntax specific to that program. For example, if you plan to generate graphics with the dot language, then install on your machine the graphviz command line tool in order to properly generate those outputs. It is for example not necessary to install Inkscape if you don’t plan to generate the documentation in PDF format.

Installation

Windows

Note

It is up to the user to choose the installation procedure based on its preference.

One can install every tools separately by using the following links:

Otherwise, use the Chocolatey package manager for Windows.

First install Chocolatey by running the following command in a Powershell terminal:

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

For any issue, please refer to the installation procedure in the official documentation of Chocolatey.

Then, run the command below (doesn’t require Powershell):

choco install python make miktex inkscape graphviz pandoc openjdk11jre

Check that Chocolatey bin folder (C:\ProgramData\chocolatey\bin) is in the PATH environment variable.

Linux

Install make, latex tools, Inkscape, Graphviz, Pandoc:

sudo apt-get install build-essential texlive-full inkscape graphviz pandoc

Install Java:

sudo dpkg --configure -a
sudo mkdir -p /usr/share/man/man1
sudo apt-get install -y openjdk-11-jre

Python Packages

The only mandatory python package to build sphinx documentation is the sphinx package. All other listed packages are added features to ease writting better docs. They are listed here because they are common in all sphinx documentations writting in the SPL group.

List of common Python packages used in SPL group to write sphinx documentation

Package name

Description

sphinx

Sphinx core package

sphinx-rtd-theme

Read the Docs theme

recommonmark

Write page in markdown syntax

sphinx-autobuild

Auto rebuild doc and livereload enabled web server

Installation (recommanded)

Usually an SPL sphinx documentation comes with a Pipfile for an easy install of all required packages. Therefore, if the Pipfile is present, make sure to have pipenv installed and run:

pipenv install

This will create a virtual environment and install not only the common packages listed above but equally all other packages added as third-party extension to the documentation.

Installation from scratch

For an installation from scratch, use the command below to install the common packages:

pip install sphinx sphinx-rtd-theme recommonmark sphinx-autobuild

Install third-party extensions:

pip install sphinxcontrib-wavedrom sphinxcontrib-plantuml sphinx-copybutton

Additionnaly, if you plan to write page as notebook file (.ipynb), the following package are required:

pip install nbsphinx IPython ipykernel

Then install any other packages required to execute cells within the notebook. For example:

pip install numpy plotly pandas matplotlib

Important

When importing a particular package within a notebook, don’t forget to add that particular package in the .gitlab-ci.yml file in order to be executed properly by the CI tool.

For more information on how to write page as jupyter notebook, please refer to Add a Jupyter Notebook page.

How to add a new package

If you write a documentation and find an useful extension to be added, follow the steps below:

  • If you use pipenv virtual environment, install the package within the environment:

    pipenv install <package_name>
    

    This will automatically add the package in the Pipfile.

    Otherwise install the package normally:

    pip install <package_name>
    

    and add manually the package in the Pipfile.

  • Add the command for the CI tool to install the package: in the .gitlab-ci.yml, add the command pip install <package_name>.

How to Build Sphinx doc locally

Sphinx documentation comes with a Makefile and one can use a predefined make command to generate the documentation in a desired output. With a terminal, cd inside the documentation where the Makefile resides and run one of the following command:

make               # list all the available output format
make help          # list all the available output format

make html          # for html
make latex         # for latex
make latexpdf      # for latex (will require latexpdf installed)

make clean         # cleans all generated file, TODO before commiting
make clean-images  # cleans all autogerated png and pdf files

make livehtml      # start a local webserver and watch files change
make openhtml      # open the generated index.html in browser

If you have installed the documentation in a virtual environment with pipenv (which is the recommanded way), you must prepend the command with pipenv run, e.g:

pipenv run make html

Otherwise, if you want run make multiple times, prepending pipenv run on each command can be annoying. Therefore, one can spawn a subshell and run commands within the virtual environment directly.

pipenv shell

Note

All generated output will be stored in the _build folder. For example HTML output is stored in _build/html and PDF & Tex in _build/latex.

The public folder is a copy of the _build/html. This latter is used by the CI tool to publish the HTML documentation and run it as a static html site.

Live preview

When writing the documentation, one can have the documentation to be built every time a change is detected in the source files and automatically refresh the web page.

To start the live server run:

make livehtml

The documentation will open automatically in your web browser.

Warning

If the server output logs doesn’t appears on the terminal after running make livehtml, just stop and restart the server. But even if it does, that doesn’t really matter. To properly resolve warning and errors, use make html.

Commit to Repository

Before performing a commit the following steps are required:

  • Verify the build of the documentation locally:

    make html
    
  • Solve important build Warnings and Errors appearing in the output.

  • Generate pdf (optional)

    make latexpdf
    

Warning

Currently pdf creation has multiple problems which should be addressed by <insert name here>!!!

  • Clean the repo from generated files

    make clean
    
  • Commit and push the changes

Continuous Integration(CI)

The .gitlab-ci.yml will run on each master commit and create a public/ folder which will be used by gitlab pages and displayed as static html pages.

Sphinx Installation How to