Création d’une première documentation sphinx

Installer sphinx

sudo apt-get update
sudo apt-get install -f python3-sphinx

Créer un répertoire pour la documentation:

mkdir -p doc/sphinx

Créer un fichier requirments.txt pour les dépendances de la documentation:

touch ~/info_indus/info_indus_tutorial/doc/sphinx/requirements.txt

Ajouter les dépendances suivantes dans le fichier requirements.txt avec vscode:

mistune < 1.0.0
myst-parser
sphinx-copybutton
sphinx-tabs
sphinx_rtd_theme
sphinx-design

Installer les dépendances:

cd ~/info_indus/info_indus_tutorial/doc/sphinx
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configurer la documentation

Initialiser la documentation avec les outils sphinx:

cd ~/info_indus/info_indus_tutorial/doc
sphinx-quickstart sphinx

Répondre aux questions posées par sphinx-quickstart.

Séparation source/build

Il est judicieux de séparer les sources du répertoire de build car du point de vue de la sauvegarde et du versionnement du projet avec git, on peut suivre tout ce qui se trouve dans le répertoire source. On ne versionne en effet pas le répertoire de build, car il contient des éléments générés automatiquement donc qui peuvent être intégralement déduits de tous les autres fichiers versionnés. On gagne ainsi beaucoup en quantité de données versionnées, c’est donc un gain de resources de temps de calcul et d’espace mémoire.

Nom du projet

Pour le nom du projet, il faut choisir un nom le plus court possible et qui soit aussi représentatif que possible du projet et de son usage. Il est courant, par exemple, de préfixer une librairie python avec le préfix py.

Pour ce projet, la règle que nous allons choisir est la suivante: utilisez les initiales des personnes de votre groupe suivi de info_indus_tutorial. Par exemple, pour le groupe d” Amélie POULAIN, Jean DUPONT et Nikita TESTU, le nom du projet sera PaDjTn_info_indus_tutorial.

Examiner les fichiers créés par sphinx-quickstart du point de vue de git

Regarder avec git les nouveaux fichiers créés:

git status

Éditer les fichiers de configuration de sphinx

Modifier le fichier conf.py:

1. mettre-à-jour les extensions,

2. mettre-à-jour le theme html de la documentation (html_theme),

3. donner les options pour l’extension copybutton,

4. donner le chemin du fichier css

Fichier de configuration de Sphinx (et oui! c’est du python)

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))


# -- Project information -----------------------------------------------------

project = "Cours d'Informatique Industrielle avec ROS2"
copyright = '2024, Manuel YGUEL'
author = 'Manuel YGUEL'

# The full version, including alpha/beta/rc tags
release = '1.0.0'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    "sphinx.ext.graphviz",
    "sphinx.ext.ifconfig",
    "sphinx.ext.intersphinx",
    "sphinx_copybutton",
    "sphinx_tabs.tabs",
    "sphinx_rtd_theme",
    "myst_parser",
    "sphinx_design",
]

myst_enable_extensions = ["colon_fence"]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'fr'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
source_suffix = [".rst", ".md"]


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'

html_sidebars = {
    '**': [
        'globaltoc.html',   # Use the global TOC instead of the local one
        'relations.html',   # Adds links to the previous and next chapters
        'searchbox.html',   # Adds a search box
    ]
}

# -- Options for copybutton extension ----------------------------------------
copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
copybutton_prompt_is_regexp = True

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

html_css_files = [
    "css/custom.css",
]

Ajouter les fichiers créés par sphinx-quickstart:

Ajouter le fichier custom.css dans le répertoire _static/css:

mkdir -p ~/info_indus/info_indus_tutorial/doc/sphinx/source/_static/css
touch ~/info_indus/info_indus_tutorial/doc/sphinx/source/_static/css/custom.css

Fichier css custom.css

/* Force line wraping in code instead of horizontal scrolling */
pre {
    white-space: pre-wrap !important;
    word-break: break-all;
}

/* Add the possibility to underline text */
.underline {
    text-decoration: underline;
}

/* This allows the content to use most of the screen */
@media (min-width: 1200px) {
    .wy-nav-content {
        max-width: 95%;
        /* This allows the content to use most of the screen */
    }
}

/** Allow caption from toctree to wrap nicely in sidebar */
.wy-menu .caption-text {
    white-space: normal;
    word-wrap: break-word;
    overflow-wrap: break-word;
    line-height: 1.1;
    /* Increase line height to prevent overlap */
    display: block;
    /* Ensure the element takes up full width */
}

Créer la documentation

Depuis le répertoire sphinx faire:

cd ~/info_indus/info_indus_tutorial/doc/sphinx
make html

La documentation est un site statique html qui se trouve dans le répertoire build/html. Le fichier index.html est la page d’accueil de la documentation. Ouvrir la documentation avec un navigateur web, par exemple firefox:

firefox ~/info_indus/info_indus_tutorial/doc/sphinx/build/html/index.html

Sauvegarder la documentation avec git

Voir l’état de votre dépôt git:

git status

Ajouter les fichiers de la documentation:

cd ~/info_indus/info_indus_tutorial/doc/sphinx
git add source
git add Makefile make.bat requirements.txt

Fair le commit des modifications:

git commit -m "First commit of the documentation"