Générer mon asciidoc dans docker

Non mais pourquoi je veux faire ça ?

Parce que j’ai des collègues qui n’ont pas installé Graphviz. Personnellement, je ne comprend vraiment pas pourquoi. Mais bon, chacun ses choix.

Donc, comme ils n’ont pas Graphviz, et ne veulent pas l’installer, qu’en bonus ils ne veulent installer ni maven, ni java, et qu’ils semblent considérer que Docker est « la meilleure chose depuis le pain en tranches » (un indice : à mon avis, c’est faux), j’ai créé une image docker « kivabien » :

Donc vous prenez ce dockerfile, là, et comme je n’aime pas trop l’idée de publier ça sur le Hub (faut voir aussi que je suis un peu une quiche en docker), ben vous le lancez … avec docker-compose et cette configuration :

d’un habile coup de docker-compose up. Et si tout se passe bien, vous allez retrouver votre dossier target votre doc correctement générée. Notez que, normalement, votre doc pourra contenir du PlantUML, des liens, toute la richesse d’asciidoc.

Elle est pas belle la vie ? Perso, je suis pas sûr, mais on me dit que c’est ça le progrès. Moi je dis ok.

 

Publicités

Asciidoc for the win !

Il y a quelques temps, j’avais écrit un article expliquant pourquoi les documents Office n’étaient pas de bons livrables. J’y indiquais par ailleurs qu’Asciidoc me semblait une bonne alternative.

Mais un format, ça n’est qu’un format. Une documentation, ça n’est hélas pas qu’un format technique de document. C’est aussi, avant tout, le moyen de raconter l’histoire du logiciel. Et parfois, ça n’est pas facile

A la recherche du bon format

Pas son histoire au sens biographique, mais plus son usage, son architecture, bref, l’ensemble des éléments qui contraignent son code à avoir sa structure. Autrement dit, les éléments qui donnent les réponses aux questions invraissemblables que se posent un développeur.

you_down_wit_opc-yeah_you_know_me

C’est pas que je déteste, c’est que je comprend pas l’histoire

Et ça, que j’écrive ma doc dans Word, en Asciidoc, en LaTeX, la question se pose toujours : pourquoi ces décisions ont été prises.

Heureusement, j’ai découvert il y a quelques temps le format de documentation agile de Simon Brown, qu’il documente dans la doc de Structurizr.

Regardons ensemble le sommaire :

  1. Context
  2. Functional Overview
  3. Quality Attributes
  4. Constraints
  5. Principles
  6. Software Architecture
  7. Code
  8. Data
  9. Infrastructure Architecture
  10. Deployment
  11. Development Environment
  12. Operation and Support
  13. Decision Log

Et maintenant, imaginez ce que ça donne pour votre projet. Tous les aspects sont documentés dans un seul gros document Word. C’est pénible … heureusement, là, asciidoc peut vous aider.

Je vous montre : si votre doc est en asciidoc, vous pouvez faire des include.

Et donc, vous pouvez avoir un dossier de doc qui ressemble un peu à ça

  • monprojet.adoc
  • images/ Vous mettez toutes vos images là-dedans
  • includes Et chacun des chapitres de votre doc est un document séparé dans ce dossier.
    • /00_intro.adoc
    • /01_context.adoc
    • /02_functional_overview.adoc
    • /03_quality_attributes.adoc
    • /04_constraints.adoc
    • /05_principles.adoc
    • /06_software_architecture.adoc
    • /07_code Si vous avez des éléments à détailler, n’hésitez pas à créer des sous-dossiers
      • /un_detail.adoc
    • /07_code.adoc
    • /08_data.adoc
    • /09_infrastructure_architecture.adoc
    • /10_deployment.adoc
    • /11_development_environment.adoc
    • /12_operation_and_support.adoc
    • /13_usage.adoc
    • /14_decision_log.adoc
    • /99_faq.adoc

Du coup, avec tout ça, vous avez une documentation correctement découpée, dans laquelle vous mettez vos diagrammes UML (ou autres) générés avec asciidoctor-diagram, et vous êtes content …

Bon, et puis si vous n’êtes pas contents de ce format, Simon Brown mentionne également le support d’arc42, qui a l’air tout aussi intéressant :

A un détail près.

Parfois, il y a du code que vous voulez voir généré pour le mettre dans la doc.

Par exemple, si vous utilisez le ServiceLoader de Java, savoir quelles classes implémentent une interface sans avoir à chercher dans Eclipse, c’est cool.

Tant qu’à générer la doc, pourquoi ne pas générer la doc ?

Parce qu’en fait, votre doc asciidoc, vous la générez, pas vrai ? Si vous faites du maven, vous utilisez sans doute le maven-asciidoc-plugin. Je vais faire l’hypothèse que vous êtes dans ce cas.

Et dans ce cas, si vous avez besoin d’avoir un morceau de la doc qui dépende plus directement du code, vous pouvez tout à fait … utiliser Groovy pour générer des fichiers asciidoc qui vont bien !

Typiquement, pour mon exemple, j’ai un script Groovy qui a dans son CLASSPATH tous les modules de mon application, et qui à l’aide de reflections recherche les implémentations de l’interface pour générer un tableau Asciidoc les affichant.

Et comme ce script Groovy est lancé grâce à gmaven avant la génération de la doc, cette partie est toujours à jour.

Et pour un projet multimodule ?

Pour l’instant, j’ai juste testé ça une fois, et d’une façon non satisfaisante. Comme j’arrivais sur un projet existant, j’ai simplement ajouté un module doc isolé du reste de l’application.

Je pense que j’aurais eu une doc d’une bien meilleure qualité si j’avais mis la doc dans chaque module avec des includes bien costauds dans la doc du module global (voire même des morceaux complètement générés). Evidement, dans ce genre de cas, la génération de la documentation doit également être documentée …

Donc ça marche bien ?

Oh que oui !

Ecrire de la doc est presque agréable, et les aspects générationnels sont une distraction encore plus agréable. Sans même parler de la fusion de cette doc et des différents diagrammes qui y sont intégrés.

Mais je crois qu’on peut aller encore beaucoup plus loin. Pas directement avec cette technique, mais sans doute en amont, via des graphes.

On pourrait faire encore mieux ?

Je vous donne quelques exemples.

Pour décrire votre applications, vous utilisez en fait plusieurs graphes

  • L’architecture conceptuelle (ou fonctionnelle) décrit comment les composants remplissent les fonctions
  • L’architecture applicative organise ces composants en modules
  • L’architecture technique montre comment ces composants se déploient.

Tout ça est censé être à peu près couvert par Structurizr.

Mais d’autres éléments ne le sont pas : quand je décris une organisation de classe, c’est aussi un graphe. Et un diagramme de séquence pourrait tout à fait être construit à partir du code un peu annoté.

Imaginez que je dispose d’un modèle comme celui de Structurizr, mais enrichi à la fois avec les informations du code (pour produire les différents diagrammes de bas niveau), et pour lequel je puisse générer des diagrammes via une quelconque syntaxe de recherche des noeuds dans un graphe. Je pourrais alors demander facilement des trucs comme

Dessine-moi le diagramme de séquence partant de cette interaction Javascript et incluant les échanges avec le serveur, la base de données, et le composant Java bidule

Et d’un coup, je n’ai plus un simple outil de documentation, mais un outil d’analyse et de compréhension de mon code, que je peux ensuite faire produire un truc que j’ai bien galéré à faire il y a quelques temps :

Fais-moi un diagramme de composant où les classes sont coloriés en fonction de leur dette technique

Bon, c’est une très chouette idée, et je sais à peu près comment l’implémenter … Mais c’est malheureusement encore un projet de plus. Et mon temps est déjà bien rempli.

Ne livrez pas de document Office !

Vous travaillez sur un grand projet … ou un moyen.

Et par exemple, on vous demande de livrer de la doc sur le code, l’architecture. ou des éléments de volumétrie. Et là vous vous dites « je livre un Excel ! » ou « Je livre un Word ! ». Par pitié, ne le faites pas.

Pas parce que c’est moche, lourd, et peu conforme à vos valeurs éthiques de partage.

Mais plutôt parce que les fichiers Office ne sont pas compatibles avec un processus de développement, ou plutôt d’écriture ?

Parce qu’après tout, votre document a bien un cycle d’écriture, non ? Vous avez bien, sous une forme ou une autre, les étapes suivantes

  • Ecriture
  • Relecture
  • Livraison
  • Passage à la version suivante

Si ça vous rappelle le cycle de vie d’artefacts de développement, ça n’est pas un hasard, c’est la même chose.

Et d’un point de vue format, comment faire ?

D’abord, si votre livrable ne bouge plus, c’est que ça n’est pas le même format que celui dans lequel vous écrivez. Typiquement, quand vous livrez un PDF, par exemple, vous ne pouvez pas vraiment le modifier (mis à part hacks visibles).

Ensuite, dans l’idéal, vous cherchez un format qui vous permette de répondre aux critiques habituelles d’Office :

  • Pas de travail collaboratif possible
  • Pas de merge
  • Un outillage de composition de document assez faible

Autrement dit, vous cherchez un format source qui soit vraiment ça : un fichier source que vous pouvez gérer dans votre SCM, sur lequel vous pouvez faire des merge, et enfin que vous pouvez composer (ou compiler) dans votre chaîne de build. Eh bien, ce format existe. En fait, il y en a plusieurs, mais un seul qui marche : Asciidoc.

De nos jours, avec Asciidoctor, vous pouvez compiler votre doc via maven, et la gérer dans votre SCM (je le fais déja). Vous pouvez par ailleurs créer de gros documents en assemblant plusieurs fragments (voir leur fameux tag include). Et, comme vous créez votre doc avec maven, elle est packagée et livrée comme le reste de votre application.

Alors, pourquoi vous continuez à utiliser Office ? Parce que vos utilisateurs le demandent ? En vrai, je ne crois pas que ce soit une bonne raison.