La documentation communautaire est nécessaire pour permettre à la communauté de comprendre le fonctionnement de votre programme/ressource sans passer par le code source, elle peut être tout aussi nécessaire pour des projets en interne, même s'il n'y a qu'un seul développeur présent.
Documenter un projet permet de s'assurer que son fonctionnement restera clair et compréhensible, et ce même dans plusieurs années. De plus, la documentation est une tache qui forcera à commenter le code, et à écrire un code plus lisible et concis.
Attention, cependant cette opération demande du temps. Au final, c'est à chacun d'estimer si son projet a suffisamment de raison d'être documenté pour consacrer du temps à cette tâche.
Le wiki présente une manière d'utiliser une suite d'utilistaires simples pour produire une documentation.
Le langage Markdown est un langage de balisage qui permet de créer facilement et rapidement de la documentation. Il est souvent utilisé pour de la documention sur des sites tel que Github. Il peut également se convertir facilement en HTML, ce qui peut s'avérer utile.
Les créateurs de Markdown trouvaient que ce n'était pas vraiment pratique de devoir mettre en forme manuellement des textes en HTML, ils ont donc créé un petit langage très simple appelé le Markdown. L'idée est de pouvoir mettre en forme du texte sans avoir besoin de recourir à la souris… et sans avoir besoin de taper à la main des balises HTML toutes les 5 secondes.
Afin de ne pas devoir écrire et réécrire ma doumentation avec différents outils pour ensuite les publier sous différentes formes j'utilise ce langage par balisage avec un simple éditeur de texte (GEDIT) pour produire des topics (court document) comportant un titre des sections et quelques paragraphes.
Ensuite les topics sont envoyés à divers programmes qui se chargeront de la mise en forme.
DokuWiki est un wiki Open Source simple à utiliser et très polyvalent qui n'exige aucune base de données. Il suffit de publié ses topics (en .txt), ou les dossiers contenant ces topics, dans le répertoire data pour que ceux-ci soient immédiatement accessibles.
Le plugin Markdowku permet la prise en charge de Markdown.
Gollum est un wiki dont la particularité est d'être propulsé par git. Il a été codé par les développeurs de Github, le choix de git n'est donc pas étonnant. Il est ainsi possible d'éditer un wiki Gollum en passant par l'interface web ou directement depuis son éditeur de texte préféré, puis en commitant dans le dépôt git utilisé par Gollum.
Gollum est une application web sous licence MIT, développée en Ruby avec le framework Sinatra, et permettant:
Le plugin gedit-markdown ajoute le support pour Markdown (ou Markdown Extra ) dans gedit, l'éditeur de texte Gnome par défaut.
Plus précisément, il ajoute:
gedit-markdown v2 prend en charge gedit 3.8 et 3.10. Il est livré avec un programme d'installation pour GNU / Linux.
Le plugin Markdown Preview dépend du paquet python3-markdown .
Pour les utilisateurs d'Ubuntu (et peut-être d'autres distributions) 11.10 ou ultérieure, le paquet gir1.2-webkit-3.0 doit être installé pour utiliser le plugin Markdown Preview .
./gedit-markdown.sh install
Le support de Markdown sera ajouté pour l'utilisateur actuel (donc pas besoin de privilèges root). Le dossier créé par l'extraction peut être supprimé après l'installation.
./gedit-markdown.sh uninstall
Le plugin Vimwiki ajoute un wiki personnel pour Vim - des fichiers texte simple liés entre eux et écrits dans un langage de balisage
Avec Vimwiki, on peut :
S'assurer d’avoir ces paramètres dans le fichier vimrc:
set nocompatible filetype plugin on syntax on
Sans eux, Vimwiki ne fonctionnera pas correctement.
git clone https://github.com/vimwiki/vimwiki.git ~/.vim/pack/plugins/start/vimwiki
RStudio est un environnement de développement gratuit, libre et multiplateforme pour R, un langage de programmation utilisé pour le traitement de données et l’analyse statistique.
L’extension rmarkdown permet de générer des documents de manière dynamique en mélangeant texte mis en forme et résultats produits par du code R. Les documents générés peuvent être au format HTML, PDF, Word, et bien d’autres1. C’est donc un outil très pratique pour l’exportation, la communication et la diffusion de résultats d’analyse.
Il permet également de produire une documentation dynamique à partir d'un document unique.
Sphinx est un générateur de documentation libre. Il s'appuie sur des fichiers au format reStructuredText, qu'il convertit, entre autres, en HTML, PDF, EPUB, ou man.
Il supporte, entre autres, l'autogénération à partir du code source ou l'intégration de formules mathématiques.
Il supporte aussi l'auto-exécution de tests intégrés dans la documentation.
L'utilisation de l'extension recommonmark permet de générer des docs Docutils & Sphinx à partir de topics en Mardown.
La documentation ainsi générée peut être automatiquement déployée sur un serveur de pages statiques (ex. JEKYLL)
Pour produire une documentation avec sphinx
$ mkdir madoc
$ cd madoc $ sphinx-quickstart
sphinx-build -b html /data/git/static/madoc/ /data/git/site1/_pages/docs/madoc
Shocco est un générateur de documentation rapide et peu élaboré, conçu pour et dans le shell POSIX.
shocco lit les scripts shell et produit une documentation source annotée au format HTML. Les commentaires sont formatés avec Markdown et présentés à côté du code mis en évidence par la syntaxe afin de donner un effet d'annotation.
La documentation ainsi générée peut être automatiquement déployée sur un serveur de pages statiques (ex. JEKYLL)