ANTIDOC

génération automatique de documentation

Olivier Jourdan <olivier.jourdan@wovalab.com>

Agenda

  1. Introduction

  2. Objectifs d’Antidoc

  3. Ce que l’on obtient avec Antidoc

  4. Comment Antidoc fonctionne ?

  5. Quelles nouvelles fonctionnalités dans le futur ?

Introduction

A propos de l’écriture de la documentation

Pourquoi écrire la documentation d’un projet ?

  • Aider à la compréhension du code

    • pour la mainenance du code

    • pour intégrer de nouveau membre dans l’équipe de développement

    • pour partager des informations avec de non développeurs

  • Repondre à des besoins normatifs

Qu’est-ce qu’il se passe habituellement ?

Si elle existe, la documentation n’est généralement pas à jour, parce que :

  • ce n’est pas la priorité

  • ce n’est pas simple à rédiger

  • nous n’aimons pas vraiment écrire la documentation

Une documentation qui n’est pas à jour est souvent pire qu’une absence de documentation

Partie I

Les objectifs d’Antidoc

Les objectifs principaux

  • Générer la documentation du code source d’un projet LabVIEW automatiquement

  • Récupérer le maximum d’information disponible dans LabVIEW:

    • Information explicite → descriptions project/class/lib/vi

    • Information implicite → liens entre les différentes composantes du code

  • Obtenir un document final dans un format standard

Objectifs des versions 1.0 et 1.1 d’Antidoc

  • Valider le process de génération du document final

  • Valider la capacité à générer une documentation réellement utile

Partie II

Qu’est-ce que l’on obtient avec Antidoc v1.1

Introduction notes

  • Récupérer de l’information implicite nécessite d’analyser le code

  • Cette information apporte beaucoup de valeur à la documentation

Actuellement, Antidoc supporte uniquement l’analyse du framework DQMH®

Générer la documentation via LabVIEW

Antidoc GUI

  • Installer Antidoc depuis VIPM

  • Ouvrir Antidoc depuis le menu
    Tools de LabVIEW

  • Générer le document

  • Ouvrir le document généré
    depuis Chrome/Opera/Firefox en
    utisant l’extension
    Asciidoctor.js Live Preview

Voila ce que vous obtenez…​

Ce document est utile pour…​

  • Intégrer de nouveaux membres dans l’équipe de développement

  • Mener des revues de design

Utiliser la ligne de commande

  • Antidoc CLI tool permet d’appeler Antidoc depuis une interface de commande

  • Utilioser Antidoc dans votre processus d’Intégration Continue

Antidoc CLI tool
Pour voir une configuration complète, étudiez ce project GitLab

Formats de sortie supportés

Quelques exemples d’utilisateurs d’Antidoc…​

Partie III

Comment Antidoc fonctionne ?

Les challenges?

Trouver le moyen de générer facilement les différents fichiers de sortie pour…​

concentrer les efforts de développement sur la récupération du contenu de la documentation.

La solution

Écrire un simple document texte…​

…​en utilisant la syntaxe AsciiDoc.

Les outils fournis par Asciidoctor s’occupe de la conversion des fichiers AsciiDoc dans le format voulu.

Comment cela marche ?

Antidoc workflow

Antidoc repose sur des projets open-sources

Antidoc est open source

Vous pouvez aider le projet Antidoc en:

  • reportant des problèmes

  • partageants des idées d’améliorations

  • contribuant au code ou à la documentation

Remerciement aux contributeurs actuels d’Antidoc

Bertrand Pouteau - Cyril Gambini - Fabiola De La Cueva
Joerg Hampel - Tatiana Boyé

Partie IV

Nouveautés à venir

Diagramme de classes UML

UML Class diagram

Support d’autres frameworks

  • Actor Framework

  • JKI State Machine Objects

  • …​

Encore plus…​

  • Améliorer l’analyse du DQMH®

  • Filtrer les éléments à ne pas documenter

  • Supporter les projets contenant plusieurs cibles

  • Proposer des documents de sortie en plusieurs langues

  • …​

Un coup d’oeil aux derniers développements ?…​

Ressources

Antidoc on vipm.io

Antidoc website

Antidoc project on GitLab

Antidoc YouTube Videos

Des questions?

Merci de votre attention