La documentation du code est un processus par lequel un programmeur documente le code. C’est un terme bien connu des ingénieurs. S’ils ne le font pas, cela conduit à une mauvaise lisibilité du code et à une maintenance difficile pour les autres membres de l’équipe.
La documentation du code est différente de la documentation du projet car elle vise principalement le fonctionnement du système, mais ces deux processus ont quelque chose en commun – les exigences d’utilisation d’un outil professionnel. Dans cet article, je passe en revue quelques outils populaires pour la création de documentation de code.
LaTex
LaTeX est un système de préparation de documents pour la composition de haute qualité. Il est le plus souvent utilisé pour des documents techniques ou scientifiques de taille moyenne à grande, mais il peut être utilisé pour presque toute forme de publication.
LaTeX n’est pas un traitement de texte ! Au lieu de cela, LaTeX encourage les auteurs à ne pas trop s’inquiéter de l’apparence de leurs documents mais à se concentrer sur l’obtention du bon contenu.
LaTeX est un système de composition de haute qualité ; il comprend des fonctionnalités conçues pour la production de documentation technique et scientifique. LaTeX est la norme de facto pour la communication et la publication de documents scientifiques. LaTeX est disponible comme logiciel libre.
Vous n’avez pas à payer pour utiliser LaTeX, c’est-à-dire, il n’y a pas de droits de licence, etc.
Pandoc
Pandoc comprend un certain nombre d’extensions utiles de la syntaxe markdown, y compris les métadonnées du document (titre, auteur, date) ; les notes de bas de page ; les tableaux ; les listes de définitions ; l’exposant et l’indice ; la biffure ; les listes ordonnées améliorées (le numéro de départ et le style de numérotation sont significatifs) ; les listes d’exemples courants ; les blocs de code délimités avec coloration syntaxique ; les guillemets intelligents, les tirets et les points de suspension ; le markdown à l’intérieur des blocs HTML ; et LaTeX en ligne. Si une compatibilité markdown stricte est souhaitée, toutes ces extensions peuvent être désactivées.
Il existe de nombreuses façons de personnaliser Pandoc pour répondre à vos besoins, y compris un système de modèles et un système puissant pour écrire des filtres.
Pandoc comprend une bibliothèque Haskell et un programme de ligne de commande autonome. La bibliothèque comprend des modules séparés pour chaque format d’entrée et de sortie, de sorte que l’ajout d’un nouveau format d’entrée ou de sortie nécessite simplement l’ajout d’un nouveau module.
Pandoc est un logiciel libre, publié sous la GPL.
Markdown
Markdown est un outil de conversion de texte en HTML pour les rédacteurs web. Markdown vous permet d’écrire en utilisant un format de texte brut facile à lire et à écrire, puis de le convertir en XHTML (ou HTML) structurellement valide.
L’objectif de conception primordial pour la syntaxe de formatage de Markdown est de le rendre aussi lisible que possible. L’idée est qu’un document formaté en Markdown doit pouvoir être publié tel quel, en texte brut, sans donner l’impression d’avoir été balisé par des balises ou des instructions de formatage. Bien que la syntaxe de Markdown ait été influencée par plusieurs filtres texte-to-HTML existants, la plus grande source d’inspiration pour la syntaxe de Markdown est le format du courrier électronique en texte brut.
LiveEdu
LiveEdu vous permet de diffuser votre documentation de code et de créer une « documentation de code vidéo ».
Education Ecosystem est un écosystème d’apprentissage décentralisé qui enseigne aux professionnels et aux étudiants des collèges comment construire de vrais produits. Vous pouvez décrire notre produit comme un hybride de Pluralsight et de Twitch. Nous construisons le plus grand écosystème d’apprentissage au monde pour les sujets technologiques futurs tels que l’intelligence artificielle, la cybersécurité, le développement de jeux, la science des données, les crypto-monnaies et la programmation. L’écosystème d’éducation est basé sur la vidéo et chaque projet contient des vidéos, un plan de projet structuré, un repo de projet et des ressources téléchargeables. Les utilisateurs peuvent cloner les ressources du projet à partir du Git d’Education Ecosystem et exécuter les applications sur leur machine locale.
Sphinx
Sphinx est un outil qui facilite la création d’une documentation intelligente et belle, écrit par Georg Brandl et sous licence BSD.
Il a été créé à l’origine pour la documentation de Python, et il a d’excellentes facilités pour la documentation de projets logiciels dans une gamme de langages. Voici quelques fonctionnalités :
- Formats de sortie : HTML (y compris l’aide HTML de Windows), LaTeX (pour les versions PDF imprimables), ePub, Texinfo, pages de manuel, texte brut.
- Références croisées étendues : balisage sémantique et liens automatiques pour les fonctions, les classes, les citations, les termes de glossaire et les éléments d’information similaires.
- Structure hiérarchique : définition facile d’une arborescence de document, avec des liens automatiques vers les frères et sœurs, les parents et les enfants.