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.