Documenter automatiquement¶
Exemple. Programme à documenter, situé dans le dossier /docs/source :
Programme permettant de créer le fichier .rst contenant le listing de toutes les directives .. autofunction:: monProgramme.mesFonctions. Une directive par fonction contenue dans votre programme. Il est situé dans le dossier /docs (contenant le fichier make.bat)
La page suivante, details_archiv.html, affiche un lien vers sa source, details_archiv.rst, qui est le produit du programme autodoc.py sur base du programme archiv.py
autosummary¶
Un fichier d’extension .py peut être appelé module.
Il est possible de créer automatiquement un index trié alphabétiquement des fonctions d’un module où, en face du nom de chaque fonction (avec le nom de ses arguments), se trouve repris la première ligne de la docstring de la fonction (si elle existe).
En cliquant sur le nom de la fonction s’affichera l’entièreté de la docstring (mise en forme).
L’index créé se trouvera dans le dossier build/source/html/generated/.
Pour créer automatiquement des index, il faut alors charger, en plus, l’extension sphinx.ext.autosummary:
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosummary'
]
On peut alors créer une page ‘list_py’, contenant:
Liste des modules
=================
.. autosummary::
:toctree: generated
archiv
autodoc
Où archiv et autodoc sont les noms des fichiers sans leur extension (.py)
Note
Le point d’entrée de tous ces programmes (.py) doivent disposer de
la condition if __name__ == '__main__' : ... et tous ces fichiers (.py)
doivent être dans le dossier : /docs/source/
Il ne reste alors plus qu’à ajouter list_py dans la zone de la directive
.. toctree:: du fichier index.rst
Graphe des fonctions¶
Le programme autodoc.py permet également de générer un fichier .dot dans le dossier /source.
Ce fichier permet de générer un fichier .svg, via la commande suivante :
docs/source$ dot -Tsvg archiv.dot > archiv.svg
Note
Le programme dot requiert l’installation préalable de Graphviz.
Clic sur le graphe¶
Chaque nom affiché contient un lien vers la documentation liée à cette fonction.
Note
Les images se trouvent dans le dossier /build/html/_images