Pour créer rapidement une documentation
(d'un programme écrit en Python)
Après une installation parfaite de Sphinx,
sphinx-quickstart docs
et répondre aux 5
questions :
Cela créera le dossier /docs et d'autres sous-dossiers.
Configurer le fichier config.py
, situé dans le dossier
/docs/source
, tel que
import os # ligne décommentée import sys # ligne décommentée # Chemin sous Linux #sys.path.append('/home/.../docs/source') # Chemin sous Windows #sys.path.append('C:\...\docs\source') # Une des deux lignes "sys.path.append(..." doit être décommentée. extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.autosummary' ] html_theme = 'classic' # modification facultative
/docs/source
le fichier, écrit en Python, à
documenter.
/docs
le programme autodoc.py
, situé
dans le dossier ...\cours\pgm\sphinx\docs
autodoc.py
python autodoc.py
. Et, répondre aux questions posées.
...\cours\logiciels\graphviz\exe
contenant le fichier dot.exedot -Tsvg xxx.dot > xxx.svg
make html
dans le terminal ouvert dans le
dossier /docs
, contenant le fichier make.bat
, devrait
s'afficher :The HTML pages are in build\html.
Le présent dossier contient : - Le dossier /docs et le fichier README.rst sont issues de l'outil Sphinx lors du "quick-start" - Les autres dossiers et fichiers sont une copie du dossier /docs/build/html Ils existent donc en double. Toutefois, les fichiers /_sources/*.rst.txt sont (ou devraient être recodés) en latin15 (pour être lisibles depuis un navigateur), via gedit > enregistrer sous > latin 15 > écraser --------------- Pour extraire les docstrings du code JavaScript : https://pypi.org/project/sphinx-js/ Avant "make html", les fichiers .rst doivent être encodés en UTF-8 Sous Windows, via NotePad++, ils peuvent être convertis en UTF-8 (après avoir fait une copie de sécurité)
TODO : Vérifier que le programme autodoc.py
tient compte des class