Documenter son projet avec Sphinx

Françoise CONIL

Présentation

Sphinx est le logiciel de documentation historique de la communauté Python.

Description

Sphinx a été initialement créé 1 2 et est utilisé pour la documentation du langage Python.

C’est un logiciel de génération de documentation, qui permet d’obtenir plusieurs formats de documentations (HTML, PDF via LaTeX, pages man, etc) à partir de sources texte au format reStructuredText ou Markdown.

Il comporte de nombreuses extensions.

Il est peu médiatisé 3 mais très employé dans la communauté Python. La plateforme Read the Docs créée en 2010 pour des projets Sphinx annonce 80k projets open source qui ne sont plus uniquement en Sphinx (MkDocs et Jupyter Book).

Une recherche un peu discriminante sur GitHub 4 pourrait laisser penser qu’il y a 60k projets sur la forge.

Développement

La communauté reste active sur le projet :

Installation

Installation packagée

La documentation d’installation 1 commence par présenter une installation globale 2 de Sphinx avec les systèmes de packages (apt, yum, brew, chocolatey) avant d’évoquer conda puis l’installation avec pip.

Warning

L’application packagée est plus ancienne que celle que vous pourriez installer par pip.

# Installation globale sur une Ubuntu LTS 22.04 en 2024
$ sphinx-quickstart --version
sphinx-quickstart 4.3.2

# Installation avec pip dans un environnement virtuel sur le même OS
$ sphinx-quickstart --version
sphinx-quickstart 7.2.6

De plus, une installation packagée n’est valable que si vous générez des documentations pour des projets homogènes en terme de version Python.

Installation par pip

Si vous prévoyez plusieurs projets Python, installez plutôt Sphinx avec pip dans un environnement virtuel.

When installing Sphinx using pip, it is highly recommended to use virtual environments, which isolate the installed packages from the system packages

$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install --upgrade pip setuptools wheel

The preferred tool for installing packages from PyPI is pip.

# -U option courte de --upgrade
$ pip install -U sphinx

Création de la documentation

Création du projet : sphinx-quickstart

La commande sphinx-quickstart génère la structure de la documentation.

$ sphinx-quickstart --sep docs
Bienvenue dans le kit de démarrage rapide de Sphinx 7.2.6.
Chemin racine sélectionné : docs
> Nom du projet: ntt
> Nom(s) de(s) l'auteur(s): Romain Vuillemot
> Version du projet []:
> Langue du projet [en]:
Fichier en cours de création /<project-path>/ntt/docs/source/conf.py.
Fichier en cours de création /<project-path>/ntt/docs/source/index.rst.
Fichier en cours de création /<project-path>/ntt/docs/Makefile.
Fichier en cours de création /<project-path>/ntt/docs/make.bat.
Terminé : la structure initiale a été créée.
Vous devez maintenant compléter votre fichier principal /<project-path>/ntt/docs/source/index.rst
et créer d'autres fichiers sources de documentation. Utilisez le Makefile pour construire la documentation comme ceci :
   make builder
où « builder » est l'un des constructeurs disponibles, tel que html, latex, ou linkcheck.
  • docs : le dossier de la documentation
  • --sep : séparer la documentation générée (HTML) des sources
  • par défaut, les sources sont au format reStructuredText, .rst

Structure générée

docs
├── build
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── index.rst
    ├── _static
    └── _templates
  • le dossier source contient la configuration (conf.py), le fichier racine de la documentation (index.rst), et les fichiers sources de la documentation
  • le dossier build contiendra la documentation générée (HTML, …)
  • les fichiers Makefile et make.bat facilitent la génération de la documentation
  • les dossiers _static et _templates servent à customiser le rendu

ATTENTION

Pour conserver les dossiers build, _static et _templates, initialement vides, ajouter à git un fichier .gitignore dans chacun de ces dossiers.

Fichier de configuration

Le fichier de configuration Sphinx 1 est un fichier Python : conf.py

sphinx-quickstart génère un fichier conf.py assez minimaliste :

# Configuration file for the Sphinx documentation builder.
project = 'ntt'
copyright = '2024, Romain Vuillemot'
author = 'Romain Vuillemot'

# -- General configuration ---------------------------------------------------
extensions = []
templates_path = ['_templates']
exclude_patterns = []

# -- Options for HTML output -------------------------------------------------
html_theme = 'alabaster'
html_static_path = ['_static']

conf.py permet de modifier et d’étendre les paramètres de la documentation, voir 2.

Fichier racine de la documentation

Le fichier racine de la documentation index.rst est un fichier reStructuredText.

Il contient par défaut le titre de la documentation, la génération de la table des matières via la directive Sphinx toctree 1 et la génération de pages spéciales via genindex, modindex et search 2.

Welcome to ntt's documentation!
===============================

.. toctree::
   :maxdepth: 2
   :caption: Contents:


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Table des matières

toctree 1 est une directive Sphinx qui permet de créer et de paramétrer une à plusieurs tables des matières dans sa documentation.

.. toctree::
   :maxdepth: 2

   getting-started
   API Reference <api/ntt>
   credits

On peut spécifier le texte d’un élément de la table des matières (une Entry) plutôt que de récupérer le titre de la page.

Ici, API Reference remplace le titre de la page api/ntt.

Générer la documentation : sphinx-build

sphinx-build 1 est la commande de génération de la documentation.

$ sphinx-build -M html source build
Sphinx v7.2.6 en cours d'exécution
...

-M est une option récente, le résultat équivaut à la commande suivante avec l’ancienne option -b

$ sphinx-build -b html source build/html -d build/doctrees

Générer la documentation : make

Le Makefile créé par sphinx-quickstart simplifie la génération de la documentation. Inutile de fournir le dossier source et le dossier destination à chaque appel.

# Génération de la documentation
$ make html
Sphinx v7.2.6 en cours d'exécution
...
La compilation a réussi.

Les pages HTML sont dans build/html.

Suppression du contenu du dossier destination

$ make clean
Removing everything under 'build'...

Enrichir la documentation

Ajouter une nouvelle page

Créer une page reStructuredText, par ex source/getting-started.rst

===============
Getting started
===============

Installation
============

You can install ``ntt`` from `PyPI`_ using ``pip`` :

.. code-block:: bash

    $ pip install ntt

It is recommended to work inside a `virtual environment`_.

.. _PyPI: https://pypi.org/project/ntt
.. _virtual environment: https://docs.python.org/3.9/library/venv.html

et la référencer dans source/index.rst pour l’ajouter à la documentation

ntt
===

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   getting-started

Ajouter une arborescence

Plutôt qu’un simple fichier, on peut vouloir une section “getting started”.

source/
├── conf.py
├── index.rst
├── getting-started.rst
├── getting-started
│   ├── overview.rst
│   └── install.rst

index.rst

ntt
===

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   getting-started

getting-started.rst

===============
Getting started
===============

Getting started with ntt

.. toctree::
    :maxdepth: 1

    getting-started/overview
    getting-started/install

Utiliser des images

Je mets habituellement mes images dans un dossier source/images.

Supposons un fichier source/credits.rst, le chemin de l’image à spécifier dans la directive .. image:: est relatif au dossier du fichier reStructuredText qui référence l’image.

=======
Credits
=======

**ntt** is written and maintained by `Romain Vuillemot`_.

.. image:: images/logo_liris.png

.. _Romain Vuillemot: https://romain.vuillemot.net/

Ajouter des références

Sphinx permet des références diverses 1

On référence une page avec le role :doc:, avec un chemin relatif.

Getting started with ntt.

You can also have a look to :doc:`ntt-workflows`

On peut référencer un emplacement “arbitraire” avec le role :ref:. Pour cela, il faut définir une étiquette (label) avant un titre, une image, ou une table ayant une légende (caption).

.. _pipeline-ex-1:

pipeline-1
==========

Here is a beginning of a Flowchart made with `mermaid`_.
Getting started with ntt.

You can also have a look to :doc:`ntt-workflows`
and to :ref:`pipeline-ex-1`.

Ajouter des documents

On référence les fichiers à télécharger via le role :download:.

J’utilise un dossier source/documents pour stocker les documents. Le chemin est relatif au dossier du fichier reStructuredText qui référence le document.

========
Overview
========

Why ntt ?
=========

**ntt** is a library that enable sport videos processing ...

.. only:: builder_html

    :download:`ntt presentation at FOSDEM <../documents/2025-02-03_ntt-fosdem.pdf>`

Note

Vous pouvez choisir de déposer vos images et vos fichiers dans le dossier courant pour avoir un chemin plus simple.

Publication en ligne

Read the docs

Read the docs est la plateforme historique de publication des documentations Python 1 2 3

Read the docs héberge 80 000 projets open source, sert 55 millions de pages par mois et 40 TB de documentation par mois. Il a 100 000 utilisateurs. L’équipe salariée semble composée de 4 personnes 4.

Le code de la plateforme est open source avec ~460 contributeurices.

Read the docs, comme PyPI, a connu une forte augmentation du nombre de projets et d’utilisateurs en 2023 5. 6.

Fonctionnement

La création d’un compte Read the docs est possible à partir d’un email / mot de passe ou en s’authentifiant avec un compte github.com, gitlab.com ou bitbucket.org.

La génération de la documentation est déclenchée sur le serveur hébergeant le repository via un webhook 1

Read the docs peut afficher plusieurs versions de la documentation.

Tutorial (GitHub)

Le tutorial montre :

  • les étapes pour créer un projet GitHub à partir d’un template d’exemple,
  • comment se créer un compte Read the docs en s’authentifiant avec GitHub, ce qui peut se faire également à partir de GitLab ou Bitbucket 1
  • comment importer simplement son projet sur Read the docs 2
  • comment configurer la génération de la documentation à l’aide d’un fichier .readthedocs.yaml placé à la racine du repository 3

La méthode proposée facilite la création de projets sur Read the docs et la configuration des webhook associés sur GitHub, mais il est possible de procéder manuellement.

Configuration manuelle

Comment configurer Read the Docs avec un repository sur GitHub, Bitbucket, GitLab, Gitea ou autre : How to manually configure a Git repository integration

Fichier de configuration .readthedocs.yaml

Exemple du fichier de configuration de la librairie ntt

# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
version: 2

# Set the OS, Python version and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.9"

  jobs:
    pre_build:
      - sphinx-apidoc -f -T -d 2 -M -o docs/source/api src/ntt

sphinx:
   configuration: docs/source/conf.py

# To install the project itself as a Python package using pip
# https://docs.readthedocs.io/en/stable/config-file/v2.html#packages
python:
  install:
    - method: pip
      path: .
      extra_requirements:
        - dev

Descriptions des éléments du fichier .readthedocs.yaml

  • build.os : spécifie l’image Docker à utiliser pour la documentation (choix entre 2 version d’une Ubuntu LTS)
  • build.tools.python : spécifie quel interpréteur Python utiliser
  • build.jobs : spécifie des commandes à exécuter avant ou après l’exécution tâches de compilation ReadTheDocs. Dans le projet ntt, on génère la documentation automatique de l’API avec sphinx-apidoc 1
  • python.install : spécifie comment installe le package documenté et/ou des “requirements”

Pour plus de détails, consulter les documentations ReadTheDocs :

Documentations strings

docstrings 1/5

Les documentations strings sont des chaines de caractères qui permettent de documenter le code. 1

Cette chaine de caractère particulière 2 est stockée dans l’attribut __doc__ de l’objet (package, module, classe, fonction, etc).

La docstring peut être utilisée par Python pour afficher de l’aide 3 4 5

Sphinx peut utiliser les docstrings pour faire une documentation d’API, …

docstrings : formats 2/5

Plusieurs formats sont supportés pour décrire les arguments, les types et les valeurs de retour.

Le plugin autoDocstring facilite l’écriture de ces docstring dans l’IDE vscode.

Format configuration du plugin autoDocstring
reStructuredText / sphinx one-line-sphinx
google google
numpy numpy

Le format google est souvent considéré comme le plus lisible, voir les exemples ci-après.

docstrings : reStructuredText / sphinx format 3/5

C’est le format historique.

def extract_last_frame(
    video_path_in: str, video_name_in: str, frame_path_out: str, frame_name_out: str
) -> str:
    """Extracts the last frame of a given video.

    :param str video_path_in: path to the folder conataining the input video
    :param str video_name_in: name of the input video
    :param str frame_path_out: path to the folder conataining the output frame
    :param str frame_name_out: name of the output frame
    :return str: full path of the output frame
    """
    pass

Note

Je n’ai pas retrouvé de documentation claire de ce format, à défaut voir : Describing code in Sphinx

docstrings : google format 4/5

C’est le format par défaut pour le plugin vscode autoDocstring.

def extract_last_frame(
    video_path_in: str, video_name_in: str, frame_path_out: str, frame_name_out: str
) -> str:
    """Extracts the last frame of a given video.

    Args:
        video_path_in (str): path to the folder conataining the input video
        video_name_in (str): name of the input video
        frame_path_out (str): path to the folder conataining the output frame
        frame_name_out (str): name of the output frame

    Returns:
        str: full path of the output frame
    """
    pass

Note

Voir google docstring format

docstrings : numpy format 5/5

Un autre format couramment utilisé (dans la communauté Calcul).

def extract_last_frame(
    video_path_in: str, video_name_in: str, frame_path_out: str, frame_name_out: str
) -> str:
    """Extracts the last frame of a given video.

    Parameters
    ----------
    video_path_in : str
        path to the folder conataining the input video
    video_name_in : str
        name of the input video
    frame_path_out : str
        path to the folder conataining the output frame
    frame_name_out : str
        name of the output frame

    Returns
    -------
    str
        full path of the output frame
    """
    pass

Note

Voir numpy docstrings standard

Intégrer la documentation du code

Intégrer des extraits de code

La directive code-block permet d’insérer une section de code, elle a plus d’options que la directive highlight, par ex :emphasize-lines:.

On peut aussi utiliser ``setrootns`` et ``defaultns`` mais c'est plus verbeux.

.. code-block:: bash
    :emphasize-lines: 2,3,9,17,18,20

    $ xmllint --shell ISRCTN17072692-internal.xml
    / > setrootns
    / > dir
    DOCUMENT
    version=1.0
    URL=ISRCTN17072692-internal.xml
    standalone=true

    / > xpath //defaultns:trialCentres/defaultns:trialCentre/defaultns:name
    Object is a Node Set :

Syntax highlighter : pygments

Pygments est la librairie Python qui réalise la coloration syntaxique de code.

Elle supporte 580 langages et formats de texte 1.

Elle offre plusieurs styles d’affichage 2 :

Extensions Sphinx : autodoc et napoleon

autodoc et napoleon sont des extensions intégrées à Sphinx : il n’y a pas de code supplémentaire à installer.

autodoc automatise l’extraction des documentations strings (docstrings) du package. L’extension apporte plusieurs directives, dont :

.. automodule::   => documenter un module
.. autoclass::    => documenter une classe
.. autofunction:: => documenter une fonction

napoleon ajoute le support des docstrings au format numpy et google.

autodoc et napoleon doivent être déclarées dans conf.py :

extensions = ['sphinx.ext.autodoc',
              'sphinx.ext.napoleon']

On peut insérer manuellement une docstring avec les directives autodoc :

**ntt** propose des fonctions utilitaires, par exemple, l'extraction d'une trame
vidéo :

.. autofunction:: ntt.frames.frame_extraction.extract_last_frame
   :no-index:

Documentation d’API : sphinx-apidoc 1/2

La commande sphinx-apidoc 1 peut générer une documentation complète d’API à l’aide des directives autodoc :

$ sphinx-apidoc -f -T -d 2 -M -o docs/source/api src/ntt
$ ls -1 source/api/
ntt.draw.rst
ntt.frames.rst
ntt.rst
...
  • -f : Force overwriting of any existing generated files
  • -T : Do not create a table of contents file 2
  • -d 2 : Maximum depth for the generated table of contents file
  • -M : Put module documentation before submodule documentation
  • -o : Directory to place the output files
  • src/ntt : path to a Python package to document

Documentation d’API : sphinx-apidoc 2/2

Inclure une référence vers le fichier généré comme point d’entrée de la documentation d’API du package, ici source/api/ntt.rst, dans la documentation.

Exemple d’inclusion dans le fichier racine index.rst 1 :

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   getting-started
   API Reference <api/ntt>
   credits

Extensions Sphinx

intersphinx

L’extension intégrée sphinx.ext.intersphinx permet d’ajouter des références 1 vers des documentations externes :

  • explicitement avec le role :external:
  • implicitement en solution de repli quand une référence n’est pas trouvée dans la documentation courante

Déclarer l’extension et définir les documentations externes dans le dictionnaire intersphinx_mapping dans le fichier conf.py.

extensions = ['sphinx.ext.intersphinx']

intersphinx_mapping = {
        'python': ('https://docs.python.org/3', None),
        'ntt': ('https://ntt.readthedocs.io/en/latest/', None)
        }

On peut ensuite ajouter des liens vers la documentation Python par exemple :

Voir :external:ref:`re-syntax` pour la syntaxe des expressions régulières en Python.

On peut mettre un lien vers la documentation d’une fonction :

Voir la documentation de la fonction :external:py:func:`re.match`

Pour faire référence à la définition présente dans la documentation Python du module re :

.. function:: match(pattern, string, flags=0)

Warning

On ne peut pas utiliser le role :doc: avec intersphinx 1

Résolution des warnings liés à nbsphinx

⇨ L’ajout de nbsphinx_widgets_path = '' a supprimé le warning suivant :

Lecture des sources... [100%] notebooks/swim_stats
WARNING: nbsphinx_widgets_path not given and ipywidgets module unavailable

⇨ L’installation de ipywidgets (via pyproject.toml) a supprimé les warnings sur les différents notebook et le code dans les cellules est syntaxiquement coloré.

/home/fconil/AMIGO/dockerisation/ntt/docs/source/notebooks/Easing_effets_visuels_3.nblink:: WARNING: Le nom du l'analyseur Pygments 'ipython3' est inconnu
/home/fconil/AMIGO/dockerisation/ntt/docs/source/notebooks/draw_bbox_with_ntt.nblink:: WARNING: Le nom du l'analyseur Pygments 'ipython3' est inconnu
/home/fconil/AMIGO/dockerisation/ntt/docs/source/notebooks/draw_cycles_in_perspective.nblink:: WARNING: Le nom du l'analyseur Pygments 'ipython3' est inconnu

⇨ De nombreuses configurations continent nbsphinx_execute = 'never' 1 ce qui parait souhaitable.

Warning

Faut-il installer ipykernel, cf nbsphinx installation ? A priori, ça n’a pas semblé nécessaire pour les notebooks de ntt.

Mermaid

Mermaid 1 est une solution qui gagne en popularité pour générer des diagrammes du fait de son intégration à GitLab.

Il y a un conflit entre l’extension nbsphinx et l’extension mermaid 2 : un hack qui a fonctionné avec les deux extensions activées consiste à ajouter nbsphinx_requirejs_path = '' à conf.py.

$ pip list
nbsphinx                      0.9.3
nbsphinx-link                 1.3.0
...
pydata-sphinx-theme           0.15.2
...
Sphinx                        7.2.6
sphinx_design                 0.5.0
sphinxcontrib-mermaid         0.9.2

Warning

Mermaid manque cruellement d’un affichage correct des erreurs et est plutôt sensible

Exemple de diagramme de séquence Mermaid

sequenceDiagram
    autonumber
    Bob->>Alice: Authentication Request
    Alice->>Bob: Authentication Response

    Bob->>Alice: dummy

    Bob->>Alice: Yet another authentication Request
    Alice->>Bob: Yet another authentication Response

    Bob->>Alice: dummy

    Bob->>Alice: Yet another authentication Request
    Alice->>Bob: Yet another authentication Response

PlantUML

PlantUML est un autre outil de génération de graphiques à partir de descriptions textuelles. Créé en 2010, facile à utiliser, il nécessite Java, graphviz et le téléchargement du jar PlantUML 1. Il a une extension Sphinx sphinxcontrib.plantuml.

J’ai pu le faire fonctionner sur Read the docs en suivant les informations de l’issue 9958: PlantUML can’t be executed. Java missing?. 2

version: 2

build:
  os: ubuntu-22.04
  apt_packages:
    - default-jdk
    - graphviz
  tools:
    python: "3.10"

sphinx:
   configuration: docs/source/conf.py

python:
   install:
   - requirements: docs/requirements.txt

Pour le test, j’ai téléchargé manuellement le jar PlantUML que j’ai intégré au projet. Il serait préférable de le faire télécharger par Read the Docs.

├── docs
│   ├── build
│   ├── make.bat
│   ├── Makefile
│   ├── requirements.txt
│   └── source
│       ├── conf.py
│       ├── diagrams
│       │   └── sequence-diagram.rst
│       ├── diagrams.rst
│       ├── index.rst
│       └── utils
│           └── plantuml-lgpl-1.2024.4.jar

Toujours sur la base de l’issue 9958, j’ai ajouté la configuration suivante au fichier Sphinx conf.py

import os

# -- Options for PlantUML ----------------------------------------------------
local_plantuml_path = os.path.join(os.path.dirname(__file__), "utils", "plantuml-lgpl-1.2024.4.jar")
plantuml = f"java -Djava.awt.headless=true -jar {local_plantuml_path}"

Exemple de diagramme de séquence PlantUML

autonumber 10 10 "<b>[000]"
Bob -> Alice : Authentication Request
Bob <- Alice : Authentication Response

autonumber stop
Bob -> Alice : dummy

autonumber resume "<font color=red><b>Message 0  "
Bob -> Alice : Yet another authentication Request
Bob <- Alice : Yet another authentication Response

autonumber stop
Bob -> Alice : dummy

autonumber resume 1 "<font color=blue><b>Message 0  "
Bob -> Alice : Yet another authentication Request
Bob <- Alice : Yet another authentication Response

Exemple de diagramme de séquence PlantUML avec thème

!theme aws-orange

autonumber 10 10 "<b>[000]"

Bob -> Alice : Authentication Request
Bob <- Alice : Authentication Response

autonumber stop
Bob -> Alice : dummy

autonumber resume "<font color=red><b>Message 0  "
Bob -> Alice : Yet another authentication Request
Bob <- Alice : Yet another authentication Response

autonumber stop
Bob -> Alice : dummy

autonumber resume 1 "<font color=blue><b>Message 0  "
Bob -> Alice : Yet another authentication Request
Bob <- Alice : Yet another authentication Response

Hieroglyph : slides

Warning

En 2012, l’extension Hieroglyph permettait de créer des slides HTML en reStructuredText avec HTML. Malheureusement, le dernier commit date de 2020-07-04 1 2 et la génération des slides déclenche une exception Jinja et un warning Sphinx.

$ pip install hieroglyph
$ mkdir my-hieroglyph-slides
$ cd my-hieroglyph-slides
$ hieroglyph-quickstart
$ make slides
    Running Sphinx v7.2.6
    ...
    done
    /home/fconil/Progs/python/sphinx/.venv/lib/python3.10/site-packages/hieroglyph/builder.py:126: RemovedInSphinx80Warning: Sphinx 8 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
      doctree.attributes.get('source')[len(self.srcdir) + 1:].count('/')
    generating indices... genindex failed
    Theme error:
    An error happened in rendering the page genindex.
    Reason: UndefinedError("'style' is undefined")
    make: *** [Makefile:20: slides] Error 2

Thèmes HTML pour Sphinx

Options de configuration de la sortie HTML

Le fichier conf.py comporte de nombreuses options 1 pour configurer la sortie HTML.

Les thèmes reposent souvent sur ces options qu’il est utile de connaître, parmi celles-ci :

Option HTML Exemple Description
html_theme pydata_sphinx_theme Identifiant du thème à appliquer
html_theme_options { 'show_prev_next': False } Options spécifiques au thème
html_logo 'images/logo_liris.png' Logo de la documentation
html_css_files ['custom.css'] Liste de fichiers de styles

Thèmes intégrés à Sphinx

Le thème par défaut, pour la documentation au format HTML, est alabaster 1 2. il est utilisé par la librairie Requests.

Vous pouvez découvrir des thèmes complémentaires sur le site sphinx-themes.org.

Thème Read the Docs

Le thème Read the Docs est un thème classique pour un projet Python.

Installer le thème via pip :

$ pip install sphinx-rtd-theme

ou via le fichier pyproject.toml :

[project.optional-dependencies]
doc = [
    "sphinx",
    "sphinx-rtd-theme",
]

puis déclarer le thème installé dans le fichier conf.py :

html_theme = 'sphinx_rtd_theme'

Thème PyData

Le thème PyData semble avoir plus de richesse dans les possibilités de configuration et de présentation. 1 2

Sphinx Design Components

Le thème peut utiliser sphinx-design 1 2 pour ajouter des composants d’interface utilisateur 3 et améliorer la création de contenus.

Il faut installer le package sphinx-design :

$ pip install sphinx-design

et déclarer l’extension sphinx_design dans le fichier conf.py

extensions = ['sphinx.ext.autodoc',
        'sphinx.ext.napoleon',
        'sphinx_design',
        'nbsphinx',
        'nbsphinx_link']

Page d’accueil avec PyData

Standard

Avec Sphinx Design Components

Mise en oeuvre des modifications

:html_theme.sidebar_secondary.remove:

.. raw:: html

    <style type="text/css">
        h1 {display: none;}
        .bd-main .bd-content .bd-article-container {max-width: 100%;}
        .big-font {font-size: var(--pst-font-size-h4); color: var(--pst-color-primary)}
        .video_wrapper.align-center {margin: auto;}
        .bd-footer-article{display: none;}
    </style>

ntt
===

.. rst-class:: big-font

``ntt`` is a modular video processing pipeline that has been used on swimming and table tennis

.. grid::

    .. grid-item-card::
        :img-top: images/Mondial_Ping-Men_s_Singles-Round_4-Kenta_Matsudaira-Vladimir_Samsonov-57.jpg
        :img-alt: "Championnats du monde de tennis de table, Paris. Huitième de finale simple homme. Kenta Matsudaira vs Vladimir Samsonov"

        "Championnats du monde de tennis de table, Paris. Huitième de finale simple homme. Kenta Matsudaira vs Vladimir Samsonov" by `Pierre-Yves Beaudouin`_ is licensed under `CC BY-SA 3.0`_

    .. grid-item-card::
        :img-top: images/Nuoto5.jpg
        :img-alt: "Nuotatore in vasca"

        "Nuotatore in vasca" by `Lorenzo Massacci`_ is licensed under CC-BY-SA-2.0


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

   getting-started

   API Reference <api/ntt>

   notebooks

   credits
   
.. _Pierre-Yves Beaudouin: https://commons.wikimedia.org/wiki/User:Pyb
.. _CC BY-SA 3.0: https://creativecommons.org/licenses/by-sa/3.0/
.. _Lorenzo Massacci: https://www.flickr.com/photos/281203/

Ce changement 1 est implémenté dans le fichier index.rst :

  • :html_theme.sidebar_secondary.remove: ⇨ supprime la Secondary Sidebar 2
  • .. raw:: html ⇨ supprime le titre de niveau 1, ntt
  • .. rst-class:: big-font ⇨ applique le style CSS big-font au paragraphe qui suit
  • .. grid::, .. grid-item-card:: ⇨ définissent les composants grid et card 3
  • :hidden: ⇨ désactive, pour cette page, l’affichage de la table des matières définie plus bas

Adaptations CSS

Theme variables and CSS

On dirait que l’on ne peut prendre qu’un nombre très restreint de “modes de colorations Pygments”, et même pas tous ceux de “accessible pygments styles” => faire une issue PyData ?

Thème Furo

Le thème Furo est un thème assez récent 1

Installer le thème via pip :

$ pip install furo

ou via le fichier pyproject.toml :

[project.optional-dependencies]
doc = [
    "sphinx",
    "furo",
]

puis déclarer le thème installé dans le fichier conf.py :

html_theme = 'furo'

Markdown et MyST

MyST étend le Markdown pour la communication et la publication scientifiques et techniques.

Intégration dans Sphinx

Sphinx utilise reStructuredText par défaut mais peut intégrer du markdown avec l’extension MyST-Parser 1

Comme pour de nombreuses extensions, on installe le package myst-parser

$ pip install myst-parser

et on déclare l’extension myst_parser dans le fichier conf.py

extensions = ['myst_parser']

On peut ensuite ajouter des pages markdown dans les sources.

MyST roles et directives

MyST 1

Directives

```{directivename} arguments
:key1: val1
:key2: val2

This is
directive content
```

reStructuredText 2 3

Directives

.. directivename:: arguments
   :key1: val1
   :key2: val2

   This is
   directive content

Roles

{role-name}`role content`

Exemple

{math}`a^2 + b^2 = c^2`

Roles

:role-name:`role content`

Exemple

:math:`a^2 + b^2 = c^2`

MyST directive code-block

La directive code-block a bien fonctionné.

```{code-block} python
:lineno-start: 10
:emphasize-lines: 1, 3

a = 2
print('my 1st line')
print(f'my {a}nd line')
```

MyST : utiliser les extensions de syntaxe

Le getting started de myst-parser présente une syntaxe 1 qui n’est pas supportée par Sphinx / myst-parser par défaut.

:::{admonition} Here's my title
:class: warning

Here's my admonition content.{sup}`1`
:::

Sphinx / myst-parser fonctionne de base avec la syntaxe suivante 2 :

```{warning}
Voici le contenu de mon avertissement. {sup}`1`
```

Il faut ajouter l’option myst_enable_extensions 3 au fichier conf.py pour que la syntaxe callout / admonitions soit supportée 4 :

myst_enable_extensions = ["colon_fence"]

MyST : mélange de syntaxes ?

Pour créer des tables, on peut utiliser la syntaxe Github Flavoured Markdown

| left | center | right |
| :--- | :----: | ----: |
| a    | b      | c     |

la syntaxe à base de callout / admonitions

:::{table} Table caption
:widths: auto
:align: center

| foo | bar |
| --- | --- |
| baz | bim |
:::

ou des directives qui semblent liées à des directives reStructuredText

```{csv-table} Frozen Delights!
:header: >
:    "Treat", "Quantity", "Description"
:widths: 15, 10, 30

"Albatross", 2.99, "On a stick!"
"Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be crunchy, now would it?"
"Gannet Ripple", 1.99, "On a stick!"
```

sphinx-quickstart ne crée pas de projet “markdown”

$ sphinx-quickstart --sep -p ntt --suffix=.md docs
Chemin racine sélectionné : docs
> Nom(s) de(s) l'auteur(s): Romain Vuillemot
> Version du projet []:
> Langue du projet [en]:

Fichier en cours de création /<project-path>/ntt/docs/source/conf.py.
Fichier en cours de création /<project-path>/ntt/docs/source/index.md.
Fichier en cours de création /<project-path>/ntt/docs/Makefile.
Fichier en cours de création /<project-path>/ntt/docs/make.bat.

Terminé : la structure initiale a été créée.

Vous devez maintenant compléter votre fichier principal /<project-path>/ntt/docs/source/index.md
et créer d'autres fichiers sources de documentation. Utilisez le Makefile pour construire la documentation comme ceci :
   make builder
où « builder » est l'un des constructeurs disponibles, tel que html, latex, ou linkcheck.
$ tree docs
docs
├── build
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── index.md
    ├── _static
    └── _templates

MyST et Quarto

Quarto que j’utilise pour ces slides utilise le Markdown Pandoc qui est une variante semble-t-il différente de MyST.

Aller plus loin

Diátaxis

Read the Docs recommande la méthodologie Diátaxis pour architecturer la documentation.

Versions de documentation

Un projet peut avoir plusieurs versions de documentations sur Read the Docs 1.

$ git tag -a 0.1.0 -m "First step reached - PlantUML activated on Read the Docs"

$ git push origin --tags
Énumération des objets: 1, fait.
Décompte des objets: 100% (1/1), fait.
Écriture des objets: 100% (1/1), 206 octets | 206.00 Kio/s, fait.
Total 1 (delta 0), réutilisés 0 (delta 0), réutilisés du pack 0
To github.com:fconil/Sphinx-with-PlantUML-on-RTD.git
 * [new tag]         0.1.0 -> 0.1.0

Via le Webhook créé sur GitHub, Read the Docs est notifié du nouveau tag créé.

Si le tag suit le semantic versionning, Read the Docs positionne une étiquette “stable” sur le dernier tag.

La branche de développement courante, par défaut : main, est référencée par l’étiquette “latest”.

Ci-contre : le panneau d’administration de versions de Read the Docs

sphinx-lint

sphinx-lint 1 est un linter pour détecter les erreurs de syntaxe reStructuredText. Installation :

$ pip install sphinx-lint

On peut exécuter sphinx-lint sur un fichier, un dossier :

$ sphinx-lint news.rst
news.rst:4043: role missing opening tag colon ( issue:`). (missing-space-before-role)
news.rst:275: trailing whitespace (trailing-whitespace)

On peut intégrer sphinx-lint à un hook git de pre-commit. Extrait du fichier .pre-commit-config.yaml de CPython utilisé par le package Python pre-commit]

  - repo: https://github.com/sphinx-contrib/sphinx-lint
    rev: v0.7.0
    hooks:
      - id: sphinx-lint
        args: [--enable=default-role, -j1]
        files: ^Doc/|^Misc/NEWS.d/next/
        types: [rst]

Internationalisation

À étudier

Je n’ai pas eu à le faire mais c’est un point à creuser.

Internationalization

Créer une extension Sphinx

Je suis tombée par hasard sur l’article The Power of Sphinx: Integrating Jinja with RST, à partir d’un lien dans le code de la documentation CircuitPython

À étudier

Le guide Écrire une extension Sphinx

Développer une extension hello world

Utilisation avec d’autres langages de programmation

Sphinx est utilisé par des projets écrits dans d’autres langages. Peut-être plus des langages historiques comme C, C++, … Par exemple :

Les domaines Sphinx, rassemblent les directives et les roles spécifiques à un langage.

Par défaut, Sphinx propose les domaines C, C++, JavaScript, Mathematics, Python et reStructuredText

.. c:function:: void hook_register(name, int (*callback)(...))
.. c:macro:: `LV_COLOR_DEPTH` ``8``: 3 x image width x image height

.. cpp:class:: template<K> nsTHashSet<K>
.. cpp:function:: V& LookupOrInsert(KeyType aKey, Args&&... aArgs) const
.. cpp:type:: std::vector<int> List

.. js:module:: RhinoCompute
.. js:function:: RhinoCompute.Extrusion.getWireframe(thisExtrusion, multiple=false)
.. py:module:: torch.nn.modules.container
.. py:exception:: XlsxWriterException

.. math:: e^{i\pi} + 1 = 0

.. rst:directive:: toctree

Ressources