En passant à Asciidoctor [2,3]!
Quoi un autre outil! non mais tu nous arnaques la, il va falloir tout refaire!
Non non ne vous inquiétez pas! Asciidoctor est un outil qui implémente (en ruby) tout le corpus de Asciidoc avec quelques petits trucs en plus.
Du coup oui il va falloir changer d’outil mais…. pas autant que vous le croyez [4]! n’oubliez pas ce dont nous parlions dans l'article précédent [1], comment rendre plus simple, plus attractive la rédaction documentaire dans le cadre d’un projet?
Et bien à l'instar d’un maven site [5] (qui est très très basique il faut l’avouer) on va également builder notre documentation technique avec Maven tout en restant (peu ou prou) compatible avec Asciidoc et sa simplicité (syntaxiquement parlant).
Avec Maven
Bien, on a déjà parlé de Maven [6] , et effectivement surtout dans le cadre de projet Java. Pourtant, si on prend un peu le point de vue du MDE/IDM, on peut considérer la documentation comme un modèle comme un autre de notre application alors si c'est un modèle, comme de l'UML ou même du code, pourquoi ne pas le compiler? Finalement il n'est qu une façon de voir une application ou un concept.Ici on va rejoindre cette idée et nous allons définir un contexte de build maven pour faire notre documentation.
Des parents
Comme nous l'avions vu dans notre article sur Maven, on ne va pas partir bille en tête dans la simple définition d’un pom. On va se débrouiller pour augmenter la reutilisabilité. Du coup on va faire des pom parent!On sait que asciidoc est naturellement fait pour produire des documents on va donc d’abord définir un parent permettant de construire ce type de doc, disons sous le format pdf puis par extension, on va tirer partie de ce premier pom pour l'étendre vers la production de présentations (il va de soit que le contenu sera le même, seul la forme change)
Pour faire ces deux pom parent, je citerai que je me suis beaucoup inspiré d’un fork d’un ami sur github [7].
Ainsi le premier pom nommé tc-asciidoctor-pdf-parent va s’appuyer sur le plugin maven dédié à asciidoctor: asciidoctor-maven-plugin [8]. Il est complété par deux plugin asciidoctor que sont asciidoctorj-pdf [9] et asciidoctorj-diagram [10, 11] permettant de générer du pdf et de gérer des diagrammes au sein du document (comme UML, Graphviz, etc…) Pour en connaître un peu plus je vous invite à consulter le source du fichier sous github ici [12].
Le second pom nommé tc-asciidoctor-html-parent propose d'étendre le premier en spécialisant la génération documentaire au profit d’une interface html supportant la présentation. De façon à rendre celle ci plus dynamique, le pom va intégrer dynamiquement lors du build, une librairie Javascript revealjs [13] qui sera downloader via le plugin maven download-maven-plugin [14]. Ensuite, le plugin asciidoctor-maven-plugin va intégrer cette librairie pour construire la présentation en html. Pour en connaître un peu plus je vous invite à consulter le source du fichier sous github ici [15].
Utilisation
Il faut maintenant réintégrer les sources précédemment utilisées et les mettre dans un projet maven héritant du dernier pom présenté (tc-asciidoctor-html-parent)On build :
mvn clean process-resources
et cela nous donne brutalement la présentation accessible ici [16].
Déjà c’est cool notre présentation à déjà bien évolué mais on voit que la compatibilité n’est pas présente à 100%.... le cadrage n’est pas parfait... Sachant cela, chacun verra midi à sa porte et choisira son approche préférée.
Conclusion
Nous n’avons pas été très loin dans l’utilisation de Asciidoc ni de Asciidoctor son équivalent, mais sont utilisation étant simple, il ne m'a pas semblé pertinent de s’attarder sur ce genre de problématique. Par contre son utilisation et les différents de logique de build existant entre les deux outils me semblait plus intéressant à montrer (sachant que Asciidoctor étant en ruby, via l’utilisation de l’installeur Ruby et de l’application Gem il est aussi possible de l’utiliser sans une industrialisation maven qui pourtant est, il me semble pertinente)Voilà ainsi dans l’avenir, si je réalise une présentation en association avec un article, je procéderai comme pour le code source, je le déposerai dans le dépôt github du blog. Cela permettra de rendre plus dynamique les articles.
Pour ceux voulant aller un peu plus loin, les références suivantes sont pour vous: [17,18,19]
Remerciements (j’en fais pas souvent):
Merci à David et Christophe qui ont piqué ma curiosité avec asciidoc. Moi qui venait de Latex et de son formalisme jusqu’au boutiste, j’ai découvert un compromis et un outil fort pratique qui je pense va devenir un compagnon régulier de ma veille. (Il ne me reste qu'a tester la construction et l’intégration des diagrammes, mais on verra ça a la volée)Références
[1] https://un-est-tout-et-tout-est-un.blogspot.com/2018/11/asciidoc.html[2] https://asciidoctor.org/docs/
[3] https://asciidoctor.org/docs/what-is-asciidoc/
[4] https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/
[5] https://maven.apache.org/plugins/maven-site-plugin/
[6] https://un-est-tout-et-tout-est-un.blogspot.com/2018/01/maven-preparons-des-parents.html
[7] https://github.com/dvaillant/coursAsciidoc
[8] https://asciidoctor.org/docs/asciidoctor-maven-plugin/
[9] https://github.com/asciidoctor/asciidoctorj-pdf
[10] https://github.com/asciidoctor/asciidoctorj-diagram/
[11] https://asciidoctor.org/docs/asciidoctor-diagram/
[12] https://github.com/collonville-tom/tc-parent/blob/master/tc-asciidoctor-pdf-parent/pom.xml
[13] https://revealjs.com/
[14] https://mvnrepository.com/artifact/com.googlecode.maven-download-plugin
[15] https://github.com/collonville-tom/tc-parent/blob/master/tc-asciidoctor-html-parent/pom.xml
[16] https://collonville-tom.github.io/tc-un-est-tout-et-tout-est-un/tc-asciidoctor-article/ascii-article.html
[17] http://www.vogella.com/tutorials/AsciiDoc/article.html[18] https://powerman.name/asciidoc/
[19] https://riduidel.wordpress.com/2017/06/16/generer-mon-asciidoc-dans-docker/
Aucun commentaire:
Enregistrer un commentaire