Génération automatique de documentation de fonctions shell

Version imprimable

19/02/2013, 22h12
jack-ft

Génération automatique de documentation de fonctions shell

L'essentiel est dans le titre.

Utilisez-vous ou connaissez-vous des outils ou des références vers des outils permettant de générer de la documentation pour un paquet de fichiers contenant les sources de fonctions shell?

Je précise que ces fonctions sont écrites en ksh (pas en ksh93), ce qui fait qu'elles n'utilisent pas le fameux getopts amélioré (qui permet de générer automatiquement l'option --help). De toute façon, ces fichiers sont destinés à être dot-sourcés par d'autres scripts. Aucune des fonctions n'est censée être "visible/lançable" au niveau du terminal.

L'input serait des commentaires normalisés en tête de chaque fonction (à écrire ou adapter en fonction de l'existant), si possible standard (si ça existe!).

L'output serait des man pages, voire de l'html, du pdf ou du latex (après, on peut toujours se débrouiller).

L'idée serait de lancer une fois l'outil pour générer la doc à intégrer au paquet (lors de la livraison du paquet de fichiers).

L'outil serait, de préférence, libre, simple, standard, etc. :P
Je ne suis pas raciste: il peut être en shell lui-même ou en perl, python, ruby, voire emacs-lisp, à la rigueur en C...
01/03/2013, 16h07
Mandraxx

Bonjour,

Vaste problème :P
Le shell est en général le grand oublié de la documentation en ligne.

S'il s'agit de faire de la documentation, le format troff (man) est l'un des plus simple à maintenir (texte simple avec peu de balises) mais de ce que je comprends, vous voudriez générer les squelettes de documentation à partir du code ?

La première idée qui vient est Doxygen (http://www.doxygen.org/) mais malheureusement, il ne gère pas le shell en natif et il faut le bricoler un peu pour que çà marche.
En revanche, je l'utilise grandement pour le C, c'est un produit formidable.

J'ai vu sur les forums que certaines personnes utilisent un produit concurrent : HeaderDoc (https://developer.apple.com/library/...tro/intro.html) mais je n'ai jamais testé...

Bon courage.
@+

une solution barbare à l'arrache mais qui marche pas mal est la convertion des scripts en leur versions "folded" & comments

ça fait par exemple une description de fonction telle que
Code:

1 2 3 4 5 6 7 8 9 10 11 12 valide() /* valide et consolide les données avant injection */ { +-----------------[valide-0]------------+ /* prendre les donnees dans le fichier paramettre */ +-----------------[valide-1]------------+ /* tester les caractères 'fantomes' */ +-----------------[valide-2]------------+ /* comparer les types */ +-----------------[valide-3]------------+ /* generer code retour 0=OK 1=caracteres fantomes corriges 2=pb type 3=autre pb */ }
par contre si il y a pas de commentaire ou de balisage de code ça sert plus à rien....
et c'est pas un document mais juste un mémo structure.

04/03/2013, 13h25
jack-ft

Citation:

Envoyé par Mandraxx

Vaste problème :P
Le shell est en général le grand oublié de la documentation en ligne.

C'est pas faux!

Citation:

S'il s'agit de faire de la documentation, le format troff (man) est l'un des plus simple à maintenir (texte simple avec peu de balises) mais de ce que je comprends, vous voudriez générer les squelettes de documentation à partir du code ?

euh... non, pas à partir du code, mais, euh... à partir du code... ;)

Je m'explique: il y a plusieurs fichiers (de code!) contenant chacun plusieurs fonctions (codées).

Presque chaque fonction est actuellement précédée de commentaires décrivant, de façon plus ou moins formelle, et à destination des utilisateurs/clients de cette fonction, ce qu'elle fait, quels sont ses arguments, code retour, etc.
Chaque fonction contient évidemment un bloc d'instructions ksh entre { } (avec d'éventuels commentaires internes, à l'usage des développeurs/mainteneurs du code de la fonction).

L'idée serait de "normaliser" à la main les commentaires précédant le début de chaque fonction (non privée), puis d'utiliser une moulinette qui prenne en entrée le fichier de code et génère dans un format "sympa" la doc des fonctions non privées à partir des commentaires trouvés dans le fichier de code (pas à partir du code proprement dit des fonctions!).

Citation:

La première idée qui vient est Doxygen (http://www.doxygen.org/) mais malheureusement, il ne gère pas le shell en natif et il faut le bricoler un peu pour que çà marche.
En revanche, je l'utilise grandement pour le C, c'est un produit formidable.

Effectivement, je l'avais éliminé car trop spécifique C...

Il me semble que pod2man pourrait être un bon candidat, notamment par sa simplicité.

Citation:

J'ai vu sur les forums que certaines personnes utilisent un produit concurrent : HeaderDoc (https://developer.apple.com/library/...tro/intro.html) mais je n'ai jamais testé...

Bon courage.
@+

Je vais regarder HeaderDoc ... (en plus, si ça vient de la pomme...)
05/03/2013, 16h44
jack-ft

J'ai commencé à lire la doc de HeaderDoc (and co).
À première vue, ça me paraît excellent! :)
Il me semble que cela répond parfaitement à nos besoins (puissance, souplesse, simplicité).
Reste à vérifier:
- si la licence est compatible avec les préconisations d'une grosse boîte... (j'ai pas eu le courage de lire toutes les (petites) lignes...)
- si ça tourne sous un os autre que MacOsX, genre linux RHEL, ce qui paraît assez probable vu que c'est du perl!
- si ça va pas donner des boutons aux libriens du coin... (qui n'aiment guère ce qui vient de la pomme)

ça commence pas très bien:

Code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
$ make
cd xmlman ; make all CC=`if [ "$DEVELOPER_BIN_DIR" != "" -a "0" != "0" ] ; then echo "gcc-4.0" ; else echo "cc"; fi` ARCH=`uname` VERS=`{ echo "10.6"; sw_vers -productVersion | sed 's/\([0-9][0-9]*\)\.\([0-9][0-9]*\)\..*/\1.\2/'; } | sort | head -n 1` ; cd ..
/bin/sh: 1: sw_vers: not found
make[1]: Entering directory `/opt/headerdoc-8.9.14/xmlman'
cc  -lxml2 -lpthread   xml2man.o strcompat.o   -o xml2man
xml2man.o: In function `writeData_sub':
/opt/headerdoc-8.9.14/xmlman/xml2man.c:730: undefined reference to `xmlUnlinkNode'
/opt/headerdoc-8.9.14/xmlman/xml2man.c:738: undefined reference to `xmlFreeNode'
xml2man.o: In function `main':
/opt/headerdoc-8.9.14/xmlman/xml2man.c:116: undefined reference to `xmlCheckVersion'
/opt/headerdoc-8.9.14/xmlman/xml2man.c:126: undefined reference to `xmlParseFile'
/opt/headerdoc-8.9.14/xmlman/xml2man.c:147: undefined reference to `xmlParseMemory'
/opt/headerdoc-8.9.14/xmlman/xml2man.c:149: undefined reference to `xmlDocGetRootElement'
/opt/headerdoc-8.9.14/xmlman/xml2man.c:173: undefined reference to `xmlFreeDoc'
/opt/headerdoc-8.9.14/xmlman/xml2man.c:174: undefined reference to `xmlCleanupParser'

:calim2:

mais ça s'est bien terminé... après un peu de compilation manuelle: :ccool:

Code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
# [jack] 130307 Installing HeaderDoc on Ubuntu
 
# Prepare the temp file
# ---------------------
sudo mkdir -p /private/tmp
sudo chmod 777 /private/tmp
 
# Needed components
# -----------------
sudo apt-get install libxml2-dev
sudo apt-get install libxml2-utils
sudo apt-get install checkinstall
sudo apt-get install perl-doc
 
# Needed perl components
# ----------------------
sudo cpan (basically answer 'yes' to configuration questions)
cpan[1]> quit
sudo cpan HTML::Parser
sudo cpan URI::Escape
sudo cpan FreezeThaw
 
# or (interactively):
 
sudo cpan (basically answer 'yes' to configuration questions)
cpan[1]> install HTML::Entities
cpan[2]> install URI/Escape.pm
cpan[3]> install FreezeThaw 
 
# Deploy the tar ball
# -------------------
cd /opt
sudo tar xzf /media/sf_Partage_VM/headerdoc-8.9.14.tar.gz 
sudo chown -R jack:jack /opt/headerdoc-8.9.14
 
# Manually compile xml2man and co
# -------------------------------
cd /opt/headerdoc-8.9.14/xmlman
cc xml2man.o strcompat.o -lxml2 -lpthread -o xml2man
cc hdxml2manxml.o strcompat.o -lxml2 -lpthread -o hdxml2manxml
cc resolveLinks.o strcompat.o -lxml2 -lpthread -o resolveLinks
 
# Make
# ----
cd /opt/headerdoc-8.9.14
make
sudo make realinstall