Un tutoriel simple sur comment documenter votre projet Python à l'aide de Sphinx et de Rinohtype

La documentation du code est l’une des tâches que je ne souhaite vraiment pas, mais je le ferai pour les notes de toute façon.

C’est probablement ce que vous entendrez lorsque j’étais étudiant en première année en informatique. Je trouve la documentation du code ennuyeuse et inutile car je sais déjà ce que fait mon code et la seule personne qui le lira probablement sera le professeur qui le vérifiera.

Je ne comprenais pas son importance jusqu’à ce qu’un jour, j’ai eu besoin de regarder le code non documenté que j’avais écrit il ya des années pour référence et au lieu de le parcourir en détail, j’ai passé beaucoup de temps à être confus quant à la façon dont j’ai structuré le projet et même comment l'exécuter.

Aujourd'hui, de nombreux outils sont disponibles pour nous aider à documenter le code. Récemment, j'ai découvert des outils qui facilitent la création de documentation intelligente et belle. Deux d'entre eux sont Sphinx et Rinohtype.

Sphinx, écrit par Georg Brandl et sous licence BSD, a été créé à l'origine pour la documentation Python et dispose d'excellentes fonctionnalités pour la documentation de projets logiciels dans plusieurs langues (Sphinx-doc.org, 2018).

Rinohtype, associé à Sphinx, offre une alternative moderne à LaTeX. Il fournit un backend Sphinx qui permet de générer de manière professionnelle des documents PDF composés (Machiels).

Dans ce didacticiel, j'utiliserai Sphinx et Rinohtype pour générer des fichiers de documentation HTML et PDF destinés à un simple projet d'API que j'ai écrit et qui gère une liste d'enregistrements de professeurs (lien de projet Github).

  1. Clonez le projet et supprimez / déplacez le dossier docs afin que vous puissiez me suivre dans la création de la nouvelle documentation.
  2. Accédez au répertoire racine du projet.
  3. Créer et activer un environnement virtuel Python 3
virtualenv -p python3 
source  / bin / activate
Ici, j’ai nommé mon environnement virtuel «venv»

4. Installez toutes les exigences du projet

pip install -r Requirements.txt

Remarque: Sphinx et Rinohtype se trouvent déjà dans le fichier exigences.txt. Si vous souhaitez les installer dans l’environnement virtuel du projet sur lequel vous travaillez, utilisez les commandes suivantes ci-dessous.

pip installer Sphinx
pip installer rinohtype

5. Créez un répertoire docs et cd dans ce répertoire.

mkdir docs
cd docs

6. Configurer le Sphinx

sphinx-quickstart
Suivez cette configuration pour l'instant. Vous pourrez le reconfigurer plus tard par vous-même.suite de la photo précédente

7. Open source / conf.py

  • Configurer le chemin vers le répertoire racine
Lignes de commentaire 15–17Changez le chemin en ‘../ ..’ et ajoutez sys.setrecursionlimit (1500)

Le chemin doit pointer vers le répertoire racine du projet et en regardant la structure du projet. Depuis conf.py, nous devrions atteindre la racine en remontant deux répertoires parents.

Structure de projet
  • Ajouter Rinohtype à la liste de l'extension
'rinoh.frontend.sphinx'
  • Ne commentez pas les éléments en latex
décommentez cesVous pouvez changer le format plus loin, ce ne sont que les valeurs par défaut.

8. Ouvrez le fichier index.rst et modifiez le contenu comme suit. (Cliquez sur le lien index.rst pour le contenu complet)

Documentation pour le code
***************************
.. toctree ::
   : profondeur max: 2
   : Légende: Contenu:

EnseignantAPI principal
====================
.. automodule :: app
   :membres:

Contrôleur TeacherAPI
======================
.. automodule :: teacherAPI.controller
   :membres:

Modèles TeacherAPI
==================
.. automodule :: teacherAPI.models
   :membres:

Base de données TeacherAPI
====================
.. automodule :: teacherAPI.database
   :membres:

EnseignantAPI peupler
====================
.. automodule :: teacherAPI.populate
   :membres:

9. Créez les fichiers de documentation HTML et PDF.

  • Toujours dans le répertoire docs exécuté
faire du html
sphinx-build -b rinoh source _build / rinoh

EDIT NOTE [16 mars 2019]: La construction du fichier pdf échouerait si votre version de Python est ≥3.7.0 (référence de publication Github)

La première ligne produirait le fichier HTML dans docs / build / html / index.html

Vue de index.htmlVue de index.html

La deuxième ligne produirait le fichier PDF dans docs / _build / rinoh / SimpleTeacherDataAPI.pdf

Page de titre de la documentationTable des matièresExemple de page de la documentation

Après avoir travaillé dans des projets d’équipe, j’ai commencé à mieux apprécier la documentation du code et même si, je ne dirais pas que c’est la tâche la plus agréable, elle est définitivement fiable et devrait être mise en pratique par les programmeurs .

Pour en savoir plus sur le Sphinx:

  • Vue d'ensemble - Documentation Sphinx 1.8.0+

Autres tutoriels utiles:

  • Documentation de votre projet à l'aide de Sphinx - Cela m'a aidé à comprendre comment documenter mon code à l'aide de docstrings Python.
  • Tutoriel Sphinx de Brandon - Didacticiel complet sur l’utilisation de Sphinx

Machiels, Brecht. “Rinohtype: Processeur de document Python - Documentation Rinohtype 0.3.1.Dev0.” Rinohtype.readthedocs.io. N.p., 2016. Web. 17 juin 2018.

Sphinx-doc.org. (2018). Présentation générale - Documentation Sphinx 1.8.0+. [en ligne] Disponible à l'adresse: http://www.sphinx-doc.org/en/master/ [Consulté le 17 juin 2018].