Journal pimydoc : insérer et actualiser de la doc

Posté par (page perso) . Licence CC by-sa
Tags :
13
7
sept.
2016

Sommaire

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.

  • # Solution maison aussi, mais plus rustique

    Posté par (page perso) . Évalué à 3. Dernière modification le 07/09/16 à 20:07.

    j'aimerais savoir comment vous faites pour résoudre le même problème !

    awk

    Ne connaissant pas bien (du tout) awk, j'ai bêtement pompé et adapté un truc sur lequel je suis tombé.

    • [^] # Re: Solution maison aussi, mais plus rustique

      Posté par (page perso) . Évalué à 2.

      En effet, awk doit permettre de faire quelque chose de très similaire; peux-tu donner un exemple ?

      Pour défendre (sans trop y croire) mon projet, ses avantages sont peu nombreux : possibilité de paramétrer depuis un fichier contenant les options retenues, script multi-plateforme, et sans doute (?) un meilleur traitement des cas particuliers comme l'ajout des caractères de fin de ligne, différents sous Windows et sous Linux.

      Tout cela est bien peu : disons qu'au moins je me suis bien amusé :)

      Trust the Python !

  • # docstrings

    Posté par (page perso) . Évalué à 3.

    Ca me parait bien compliqué par rapport à un besoin qui a l'air simple: si c'est juste pour remplacer des chaînes dans des docstring, pour du python. Pour ce cas là, il est facile de manipuler les docstring, de les formater avec un __doc__.format(...), voir de faire un décorateur pour ça. Il y a aussi tout ce qu'on peut faire quand on génère du HTML avec Sphinx.

    Après ton projet est plus général, c'est peut-être un point important pour toi, ça dépend du besoin.

    • [^] # Re: docstrings

      Posté par (page perso) . Évalué à 1. Dernière modification le 07/09/16 à 22:39.

      Au risque de défendre l'indéfendable, mon programme ne concerne pas que Python et ses docstrings; la doc peut être introduite par des commentaires commençant par "#" (voir l'exemple que je donne dans le README.md). D'autre part, j'utilise Pimydoc avec d'autres langages, par exemple un projet en C++.

      Merci d'avoir parlé de __doc__.format(), je ne connaissais pas.

      Trust the Python !

      • [^] # Re: docstrings

        Posté par (page perso) . Évalué à 7.

        Oui ok, pour d'autres langages peut-être ;), mais pour des projets Python autant éviter de recourir à un outil externe.
        __doc__ est une simple string:

        >>> def foo():
        ...     """Super fonction
        ... 
        ...     {paragraph}
        ...     """
        ...     pass
        ... 
        >>> foo.__doc__
        'Super fonction\n\n\t{paragraph}\n\t'
        >>> help(foo)
        Help on function foo in module __main__:
        
        foo()
            Super fonction
        
            {paragraph}
        
        >>> foo.__doc__ = foo.__doc__.format(paragraph="Un paragraphe")
        >>> help(foo)
        Help on function foo in module __main__:
        
        foo()
            Super fonction
        
            Un paragraphe
        • [^] # Re: docstrings

          Posté par (page perso) . Évalué à 1.

          Très intéressant, en effet. Je me répète cependant : avec ta méthode on manipule les docstrings (et c'est déjà beaucoup), pas les commentaires commençant par dièse. Merci de l'exemple !

          Trust the Python !

Suivre le flux des commentaires

Note : les commentaires appartiennent à ceux qui les ont postés. Nous n'en sommes pas responsables.