URL: https://linuxfr.org/users/suizokukan/journaux/pimydoc-inserer-et-actualiser-de-la-doc Title: pimydoc : insérer et actualiser de la doc Authors: Xavier Faure Date: 2016年09月07日T17:49:37+02:00 License: CC By-SA Tags: documentation Score: 13 **en bref** : un micro-micro-[projet](https://github.com/suizokukan/pimydoc) 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](https://github.com/suizokukan/pimydoc). 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](https://pypi.python.org/pypi/Pimydoc/). 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](https://raw.githubusercontent.com/suizokukan/pimydoc/master/pimydoc/pimydoc). #(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.

AltStyle によって変換されたページ (->オリジナル) /