Journal pimydoc : insérer et actualiser de la doc

Sommaire

• (1) l'histoire
• (2) le nom
• (3) installation
• (4) utilisation
  • (4.1) écrire le fichier pimydoc
    • (4.1.a) l'en-tête du fichier pimydoc
      • REGEX_SOURCE_FILTER
      • STARTSYMB_IN_DOC
      • PROFILE_PYTHON_SPACENBR_FOR_A_TAB
      • REMOVE_FINAL_SPACES_IN_NEW_DOCLINES
    • (4.1.b) la documentation dans le fichier pimydoc
  • (4.2) modifier le répertoire courant :
  • (4.3) autres options
    • --sourcepath
    • --docsrcfile
    • --verbose, -vv, -vvv
    • --remove
    • --securitymode
• (5) Et la suite ?

en bref : un micro-micro-projet Python3/CLI/Win-OSX-Linux/GPLv3 qui permet d'insérer dans des fichiers cibles de la doc source stockée à part. Quand la doc source change, les fichiers cibles sont actualisés.

Un exemple :

pimydoc est le fichier où vous stockez la documentation à insérer :

REGEX_SOURCE_FILTER : .+py$      # pour ne cibler que les fichier Python
STARTSYMB_IN_DOC :¤              # marqueur utilisé dans le code pour identifier un commentaire Pimydoc

[ressource::001]
An interesting ressource.
[ressource::002]
Another interesting ressource.

un exemple de fichier cible avec deux appels pour insérer de la doc :

def foo(arg):
    """
       ressource::001
    """
    #ressource::002
    print("...")

le fichier cible devient alors (après appel à Pimydoc) :

def foo(arg):
    """
       ressource::001
       ¤ An interesting ressource.
    """
    #ressource::002
    #¤ Another interesting ressource.
    print("...")

Si vous changez le fichier pimydoc en :

REGEX_SOURCE_FILTER : .+py$      # pour ne cibler que les fichier Python
STARTSYMB_IN_DOC :¤              # marqueur utilisé dans le code pour identifier un commentaire Pimydoc

[ressource::001]
Nothing interesting here.
[ressource::002]
Another interesting ressource.

le fichier cible devient alors (après appel à Pimydoc) :

def foo(arg):
    """
       ressource::001
       ¤ Nothing interesting here.
    """
    #ressource::002
    #¤ Another interesting ressource.
    print("...")

Remarquez que Pimydoc insère la documentation en ajoutant, avant chaque ligne à ajouter, les mêmes caractères que ceux précédant la ligne qui déclenche l'insert : avant ressource::002 se trouve 5 caractères (4 espaces + #), caractères qui sont par conséquent ajoutés avant ¤ Another interesting ressource. .

De l'aide est disponible dans le fichier README.md : voyez ici.

Voyez aussi le résultat de $ pimydoc -h .

(1) l'histoire

Dans certains projets, j'ai besoin de placer les mêmes paragraphes de doc à différents endroits de mon code source. Plutôt que d'ajouter des renvois peu clairs (exemple : doc::001) qui renverraient le lecteur à un passage de la documentation ainsi intitulée), je propose un outil permettant d'insérer automatiquement de tels renvois.
Après avoir écrit un script vite fait mal fait j'ai décidé de finaliser le projet. Il s'agit d'un micro-projet probablement surdimensionné : si tel est le cas, j'aimerais savoir comment vous faites pour résoudre le même problème !

(2) le nom

pimydoc : p[lease] i[nsert] my doc[umentation]

(3) installation

$ pip3 pimydoc

car le projet est hébergé sur Pypi.

ou bien :

$ wget https://raw.githubusercontent.com/suizokukan/pimydoc/master/pimydoc/pimydoc.py

puisque ce projet n'est constitué que d'un seul fichier Python. Vous aurez cependant besoin d'un fichier "pimydoc" : vous pouvez vous inspirer de celui par défaut.

(4) utilisation

(4.1) écrire le fichier pimydoc

Ce fichier contient la documentation à insérer et quelques réglages :

[pimydoc]
REGEX_SOURCE_FILTER : .+py$
STARTSYMB_IN_DOC :| | 
PROFILE_PYTHON_SPACENBR_FOR_A_TAB : 4
REMOVE_FINAL_SPACES_IN_NEW_DOCLINES : True

[exit codes]
0:ok
-1:problem

(4.1.a) l'en-tête du fichier pimydoc

Elle suit la syntaxe key:value, pas la syntaxe key=value.

REGEX_SOURCE_FILTER

Définir les fichiers à traiter dans le répertoire cible. Il s'agit d'une regex !

STARTSYMB_IN_DOC

Caractère(s) signalant les lignes insérées par Pimydoc. Attention de ne pas prendre une combinaison déjà existante dans votre code, par exemple || pour le C++ ou __ en Python.
Vous pouvez ajouter un espace avant/après votre(vos) symbole(s) : "STARTSYMB_IN_DOC:| |" n'est la même chose que "STARTSYMB_IN_DOC: | | " par exemple.

PROFILE_PYTHON_SPACENBR_FOR_A_TAB

Si ce nombre est supérieur à 0 et si le fichier est un fichier Python, toute ligne ajoutée verra ses tabulations transformées en espaces, le nombre d'espaces étant défini par la valeur de PROFILE_PYTHON_SPACENBR_FOR_A_TAB.

REMOVE_FINAL_SPACES_IN_NEW_DOCLINES

Si initialisé à True, toute ligne ajoutée verra ses espaces à droite supprimés.

(4.1.b) la documentation dans le fichier pimydoc

Elle commence par un titre et est suivie de lignes :

[titre]
ligne1
ligne2

(4.2) modifier le répertoire courant :

Placez le fichier pimydoc dans le répertoire courant (ou utilisez l'option --docsrcfile pour indiquer où se trouve ce fichier) et lancez le script :
$ pimydoc
ou, si vous voulez plus de détails :
$ pimydoc -vv

La liste des fichiers modifiés est affichée par le script.

(4.3) autres options

Outre -v (version) et -h (aide) vous disposez des options suivantes :

--sourcepath

indique où trouver le répertoire cible

--docsrcfile

indique où trouver le fichier pimydoc contenant la documentation à insérer

--verbose, -vv, -vvv

Règle la quantité de messages affichés; -vvv affiche les messages de débogage.

--remove

Si cette option est utilisée, Pimydoc supprimera du répertoire cible toute la documentation qui aurait été insérée auparavant

--securitymode

Avec cette option, les fichiers à modifier sont d'abord sauvés sous forme d'un backup qui n'est pas effacé à la fin de l'appel au script.

(5) Et la suite ?

J'ai essayé d'écrire du code lisible par tous : pylint à 10, documentation abondante, commentaires et documentation en anglais…
Je serais ravi de vos commentaires et de vos suggestions d'amélioration ! Merci d'avance.