Documenter manuellement¶
Non seulement Sphinx permet de générer toute documentaion scientifique, mais aussi nativement la documentation des programmes codés en Python, C, C++ et JavaScript.
https://www.sphinx-doc.org/en/master/tutorial/describing-code.html
Un code peut contenir des commentaires.
Certains commentaires peuvent être récupérés : les docstrings.
Le contenu d’une docstring (contenue dans un code) est encadré. Une ligne précède et suit ce contenu. Ces lignes sont identiques.
Lorsque ce code est Python, elles ne contiennent que """.
Exemple d’une docstring, dans du code Python:
"""
Cette fonction retourne une string composée de caractères autorisés.
:param str msg: message affiché avant le curseur
:param str str_carac: liste des caractères.
:param bool isCaracOK: Indique que le second paramètre représente la liste des caractères autorisés (True, par défaut) ou la liste des caractères interdits (False)
:param bool isVideOK: Indique que la valeur de retour peut être vide (True) ou pas (False,(par défaut)
:return: Une string tapée (ou collée) par l'utilisateur
:rtype: str
"""
Note
Sphinx a été codé en Python. Et, la documentation officielle de Python est générée par Sphinx.
Si le langage (domaine) n’est pas précisé (py:, cpp:, …), avant function::, l’outil considère alors que le code a été écrit en Python.
Le bloc qui est lié à une directive .. py:function:: (ou .. function::) doit débuter par la définition de la fonction.
Exemple:
.. function:: input2(msg, str_carac=FILENAME, isCaracOK=True, isVideOK=False)
Maintenant, si la docstring ci-dessus suit cette définition, le rendu (HTML) sera :
- input2(msg, str_carac=FILENAME, isCaracOK=True, isVideOK=False)¶
Cette fonction retourne une string composée de caractères autorisés.
- Parameters
msg (str) – message affiché avant le curseur
str_carac (str) – liste des caractères.
isCaracOK (bool) – Indique que le second paramètre représente la liste des caractères autorisés (True, par défaut) ou la liste des caractères interdits (False)
isVideOK (bool) – Indique que la valeur de retour peut être vide (True) ou pas (False,(par défaut)
- Returns
Une string tapée (ou collée) par l’utilisateur
- Return type
str
Si, en plus, la docstring est codée en reStructuredText, la documentation (générée par Sphinx) en tiendra compte.
Exemple:
"""
Cette fonction retourne une string composée de caractères autorisés.
:param str msg: message affiché avant le curseur
:param str str_carac: liste des caractères.
.. note::
Par défaut, vaut FILENAME qui est une liste des caractères autorisés dans un nom de fichier.
Soit : ``abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_``
:param bool isCaracOK: True (par défaut)
* Si **True**, second argument = la **liste des caractères autorisés**
* Si False, second argument = liste des caractères interdits
* NB : Le contrôle est sûr en n'autorisant que des caractères autorisés, mais plus lent si quasi tous les caractères sont autorisés
:param bool isVideOK: False (par défaut)
* Si True, la valeur de retour peut être vide
* Si **False, la valeur de retour ne peut pas être vide**
* NB : Ci-dessous, une formule mathématique qui n'a aucun rapport avec la fonction !
.. math::
nombre~d'or = \varphi = \frac{1+\sqrt{5}}{2} = 1,618...
:return: Une string tapée (ou collée) par l'utilisateur
:rtype: str
"""
Le rendu (HTML) sera alors :
- input3(msg, str_carac=FILENAME, isCaracOK=True, isVideOK=False)¶
Cette fonction retourne une string composée de caractères autorisés.
- Parameters
msg (str) – message affiché avant le curseur
str_carac (str) – liste des caractères.
Note
Par défaut, vaut FILENAME qui est une liste des caractères autorisés dans un nom de fichier. Soit :
abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_- Parameters
isCaracOK (bool) –
True (par défaut)
Si True, second argument = la liste des caractères autorisés
Si False, second argument = liste des caractères interdits
NB : Le contrôle est sûr en n’autorisant que des caractères autorisés, mais plus lent si quasi tous les caractères sont autorisés
isVideOK (bool) –
False (par défaut)
Si True, la valeur de retour peut être vide
Si False, la valeur de retour ne peut pas être vide
NB : Ci-dessous, une formule mathématique qui n’a aucun rapport avec la fonction !
\[nombre~d'or = \varphi = \frac{1+\sqrt{5}}{2} = 1,618...\]- Returns
Une string tapée (ou collée) par l’utilisateur
- Return type
str
NB : Une même fonction ne peut pas être documentée plusieurs fois (d’où input3, ci-dessus).
Taper une directive et coller la signature d’une fonction et sa docstring manuellement, dans un fichier d’extentsion .rst, pour chaque fonction, est une tâche qui devient vite fastidieuse.
L’outil peut être configuré pour réaliser ce travail à votre place.