En fait la documentation semble séparée du code dans readthedocs. Déjà tu devrais ajouter doc/_build
au gitignore et faire un git rm
dessus, ça n'a rien à faire dans les sources, c'est un artefact de compilation de la documentation.
Tu as déjà un fichier doc/index.rst
. Ce fichier est au format rst. Toute ta doc' sera en rst, ren n'est dans le code. Tout ce que tu as à faire, c'est éditer des fichiers rst dans ton dossier doc
et lancer make html
quand tu veux prévisualiser. Fais attention à ne pas committer les fichiers que ça génère. Derrière, c'est Sphinx que ça utilise.
Plutôt que te filer la documentation, regarde comment fait ZdS. Ils ont juste les deux fichiers puis un sous-dossier source
. La doc' générée par Sphinx est ici. Fais attention à la visualisation des fichiers rst par github, ils ne te montrent pas tout. Il faut utiliser le bouton "Raw" pour voir le texte brut.
Et pour la documentation du code en lu-même, fais une section sur l'architecture du projet dans ta documentation, et dans le code utilise les docstrings.
EDIT: Apparemment on peut dire à Sphinx d'aller chercher la documentation du code dans les docstrings, comme ça, et voilà le résultat. C'est de la bombe ce truc, je m'en rendais pas compte de la puissance …
Voilà le tuto de Sphinx pour le reste.