HACK this documentation#

Todo

This section need to be reviewed.

Note

While the RST and Sphinx Cheatsheet provides general tips to write documentation with Sphinx and with the installed extensions, this section describes more precisely how we make use of sphinx and the installed extensions.

If you want to add your page to this documentation you need to add your source file in the appropriate section. Every main section has its own folder structure and its own img/ folder containing all images for this section.

This documentation uses a recursive index tree: every folder have a special index.rst file that tell sphinx witch file, and in what order put it in the documentation tree.

If you don’t have enough knowledge about ReStructuredText then you can also use the pandoc translator or use the internal Cheatsheet.

New Documentation Section#

If you want to add a new section, you need to specify in the main index.rst, the section/index.rst file of the new section.

.. toctree::
   :hidden:
   :maxdepth: 2
   :titlesonly:
   :caption: Content

   ros/index
   rst/index
   linux/index
   about/index
   section/index

The section name should be the same as the folder name, but for Sphinx this is not required. Sphinx will take the name of the section from the title of the section/index.rst file.

Example Section#

I want to document the new topic in SPL Knowhow repo, and want to create a section for it; let’s call it Section

So I need to create a folder named section/ (name is not important), and in it create a section/index.rst file like:

.. figure:: img/section-logo.*
   :align: right
   :alt: Section Logo
   :width: 300px

=============
Section Title
=============

.. contents:: :local:

.. toctree::
   :glob:
   :maxdepth: 2
   :titlesonly:
   :caption: Content

   *

Note

The .. toctree:: directive accept some parameters, in this case :glob: makes so you can use the * to include all the remaining files.

Note

The file path is relative to the index file, if you want to specify the absolute path, you need to prepend /

Now I can add additional ReST files like section/intro.rst and other files like section/section_part_1.rst, ssection/ection_part_2.rst, etc.

Section Images#

Add an image folder in the section folder section/img and add it the the Makefile in the variable IMAGEDIRS

# IMAGEDIRS can be a list of directories that contain SVG files and are relative to the SOURCEDIR
IMAGEDIRS     = img ros/img linux/img algorithms/img machinelearning/img section/img

Write the contents#

That’s it, now you can add all you want in the new section section and all pages will show up in the documentation automatically.

Add a Jupyter Notebook page#

Sometimes it is valuable to add some functionnality in a particular page to generate content automatically. In sphinx this can be achieved by adding custom directives throught extensions. However with the nbsphinx extension, one can avoid the pain to understand the sphinx extensions API and write dynamic content generation directly in a jupyter notebook file (.ipynb).

With the nbsphinx extension installed, sphinx is able to parse .ipynb files and generate static HTML page of that notebook.

One can add the .ipynb files directly in the toctree as normal .rst file:

.. toctree::
   :hidden:
   :maxdepth: 2

   page1
   page2
   mynotebook

Whenever the documentation is built, every notebook that doesn’t have at least one output cell are evaluated automatically.

Note

One can hide cells from the HTML output by adding "nbsphinx": "hidden" in the metadata of the cell.

However there isn’t actually a specific method to hide only input cells. But one can add the following code in the notebook to hide input cells with javascript when the page is loaded.

from IPython.core.display import display_html
display_html('<script>jQuery(function() {if (jQuery("body.notebook_app").length == 0) {jQuery(".input_area").toggle(); jQuery(".prompt").toggle();}});</script>', raw=True)

Warning

Be aware that the python modules used in the notebook must be available on the machine where the documentation is generated. Therefore, one must consult the .gitlab-ci.yml file to verify that a particular module is available (as pip install command) before committing the documentation to the CI server.

To find more options how to configure and write a notebook for a better integration in a sphinx documentation, please consult the official documentation.

Create page Tags#

For each page corresponding tags should be used, see SPL Doc Tags for all currently used tags.

:tag:`RST`
:tag:`ReST`
:tag:`Sphinx`

RST ReST Sphinx