Création de documentation

[yannick85]

Petit billet du samedi matin (faudrait pas prendre ça pour habitude )
'========================================================='
Hello, suite au message de @papinou concernant le passage progressif du code kernel du noyau Linux vers le langage Rust, je suis allé faire mon premier "hello world" en Rust. Comme quoi, les publications des uns et des autres servent bien à quelque chose ! J'ai alors trouvé que la documentation concernant Rust était fort bien faite (https://jimskapt.github.io/rust-book-fr/). J'ai alors farfouiné pour voir avec quel système cette doc avait été faite. Il s'agit d'un système appelé "MdBook" (Markdown book). Je vous laisse le lien pour créer vos propres documentations (en anglais malheureusement, pas vu de traduction). J'ai essayé de faire mes premières pages et ça fonctionne bien (à priori) :
https://rust-lang.github.io/mdBook/index.html
Les pages sont à écrire en langage Markdown, un langage assez simple pour faire des pages de doc en général et qui commence à prendre de l'ampleur un peu partout (bon rapport simplicité/fonctionnalité).
A côté de ça, je suis en train de consulter la documentation de Texinfo, le système conçu à la base pour documenter les logiciels Gnu (mais qui peut servir aussi pour d'autres docs). Attention, on passe à un autre niveau de complexité (du bon vieux made in Richard Stallman avec un mélange de Latex).
https://www.gnu.org/software/texinfo/
Je fini mon billet avec un petit mot concernant les pages de man. J'ai toujours trouvé, ces pages de manuel linux un peu imbuvables pour un débutant et par hasard (?), j'ai trouvé dans le livre "Linux Kernel Programming" (je ne sais pas dans quoi je me lance, là !!) qu'il existait un système appelé appelé Tl;dr (Too long; Didn't read = trop long, je n'ai pas lu, comme les pages de man trop touffues). Ce système a donc été conçu pour donner la documentation pour les options courantes des logiciels en ligne de commande. Voir : https://tldr.sh/ . Le pdf résume de nombreuses commandes : https://tldr.sh/assets/tldr-book.pdf (penser à activer la table des matières à gauche dans le pdf).
Pour installer le système tldr :

#regarder si npm (gestionnaire de paquets de node js) est installé :
>npm --version
#si ce n'est pas le cas, l'installer en mode admin (debian, ubuntu) :
>sudo apt install npm
#vérifier que npm est maintenant installé
>npm --version
#récupérer le paquet tldr
>npm install -g tldr
#fixer les vulnérabilités si besoin
>sudo npm audit fix
>npm i --package-lock-only
#tester si tldr est bien installé
>tldr --version
#utiliser tldr pour voir les infos sur la commande cp (copie de fichiers)...
#vous aurez droit à une mise à jour de la base de donnée la première fois
>tldr cp
#pour avoir l'aide sur tldr :
>tldr --help
#pour mettre à jour la base de donnée
>tldr --update

Et Voilà ! (Autentica qualità). Bon We.

[Menfi]

Bel exposé sur le sujet.

Il existe plusieurs logiciels (générateur de site statique) tel que MkDocs pour créer une documentation en ligne à partir de fichiers en markdown. Cependant ils nécessitent tous un apprentissage plus ou moins long (commande build, serve, etc. structure de fichiers, langage markdown, etc.).

Les wiki (non mentionnés) permettent aussi de mettre en place une documentation (collaborative) et sont accessibles à tous avec très peu de connaissance.