Forem: Nicolas Giraud

Doc as code, personnaliser vos rendus pour répondre à vos contraintes ou à votre esprit créatif !

Nicolas Giraud — Tue, 21 May 2024 07:30:00 +0000

Produire des documents avec les outils de doc as code reste quelque chose d'accessible à quiconque travaillant avec un IDE.
Toutefois, nos structures nous contraignent à utiliser des visuels pour produire ces documents, qu'ils soient internes ou externes.
Palettes de couleurs, chartes graphiques, design systems, sont des exemples de contraintes à appliquer dans nos processus de partage d'informations.

Le parcours initiatique pour publier, vous a peut-être conduit jusqu'ici.
Si la joie d'avoir publié vos premiers documents est bien là, la frustration qu'ils ressemblent à tous les autres n'est sûrement pas loin.

Mais comment personnaliser vos styles pour que vos documents web ou traitement de texte ne ressemblent pas à tous les autres ?
Je vous invite ici à découvrir quelles sont les possibilités de ces outils et d'identifier les points limitant pour votre créativité.
Mais avant tout, je dois vous présenter les différentes façons de configurer le générateur Asciidoctor¹.

Cette version de l'article a été publiée avec la chaîne de publication de l'écosystème Asciidoc².

Configurer le générateur

Produire et partager des documents reste relativement aisé.
Pour autant, si vous avez besoin de les personnaliser, vous devrez vous armer de patience pour configurer vous outils de génération.
Il existe un ensemble de propriétés permettant de surcharger les comportements par défaut du générateur Asciidoctor¹, et ainsi appliquer vos propres styles.

Par défaut, nous allons pouvoir utiliser des fichiers de configuration pour adapter le comportement du générateur pour un ensemble de documents.
Des propriétés pourront aussi être définies directement dans chaque document pour surcharger les fichiers de configuration.
Il sera également possible de passer des paramètres communs en les ajoutant à la commande de génération.

L'ordre de priorité des paramètres est :

Les propriétés posées sur un document

Les paramètres passés sur la commande de génération

La configuration fichier

Une fois que vous aurez réussi à configurer votre générateur, la suite de votre aventure se passera dans des fichiers CSS³.
En fonction de votre spectre de compétences, cette personnalisation vous sera plus ou moins accessible.
Malheureusement, je ne pourrai pas vous montrer ici les méandres de ce langage et vous laisserai explorer ses possibilités.

Personnaliser une feuille de style

Dans le petit guide illustré pour mieux se lancer, vous avez pu découvrir que les outils de docs as code comme Asciidoctor¹ permettent de générer vos documents au format HTML⁴.
Et comme tout bon HTML, il est possible de donner du style à nos écrits grâce à CSS³.

Selon votre degré de maîtrise du CSS³, vous pourrez partir d'une feuille de style existante, ou en écrire de nouvelles en intégralité.

L'écriture intégrale d'une feuille CSS impliquera une bonne maîtrise de la structure HTML générée.
Vous devrez pour cela vous plonger dans Asciidoctor pour connaitre ce qu'il produit.

Je vous préconise de repartir d'un thème existant afin de minimiser l'effort de compréhension du HTML généré.

Une fois votre feuille écrite, ou modifiée, il faut maintenant l'appliquer à vos documents.

Comme vu dans la section précédente, voici les trois méthodes possibles.

.asciidoctorconfig:

:stylesdir: {asciidoctorconfigdir}/.asciidoctor <1>
:stylesheet: fundation-lime.css <2>

La variable aasciidoctorconfigdir correspond au répertoire où se trouve le fichier .asciidoctorconfig
Nom complet du fichier dans le répertoire.

On pourra utiliser de la même façon ces propriétés directement dans les fichiers sources.

En revanche, leur portée est au niveau fichier, et non générateur

Les mêmes propriétés pourront également être passées dans la ligne de commande.

command line:

asciidoctor -a stylesdir=.asciidoctor -a stylesheet=fundation-lime.css docs-as-code-03-styles.adoc

Du style dans vos PDF

Si vous souhaitez utiliser les fonctionnalités de génération PDF d'Asciidoctor¹, la personnalisation des rendus sera quelque peu différente de nos habitudes de développement.
La production de PDF se fait grâce au plugin asciidoctor-pdf⁵.
Cet outil n'utilise pas CSS pour appliquer son style, mais un fichier de configuration YAML.

.exemple de fichier de template

extends: base
page:
  layout: portrait
  margin: [0.75in, 1in, 0.75in, 1in]
  size: Letter
base:
  font-color: #333333
  font-family: Times-Roman
  font-size: 12
  line-height-length: 17
  line-height: $base-line-height-length / $base-font-size
role:
  removed:
    font-style: italic
    text-decoration: line-through
    text-decoration-color: #FF0000
heading:
  font-color: #262626
  font-size: 17
  font-style: bold
  line-height: 1.2
  margin-bottom: 10
link:
  font-color: #002FA7
list:
  indent: $base-font-size * 1.5

Pour plus de détails sur ces fonctions de personnalisation, vous pouvez vous reporter à la documentation du plugin.

Comme pour le CSS, nous allons maintenant devoir appliquer cette configuration au générateur PDF.

.asciidoctorconfig

:pdf-themesdir: {asciidoctorconfigdir}/.asciidoctor <1>
:pdf-theme: pdf <2>

la variable aasciidoctorconfigdir correspond au répertoire où se trouve le fichier .asciidoctorconfig
Préfixe du fichier de configuration. Dans ce cas, le fichier s'appelle pdf-theme.yml

On pourra utiliser de la même façon ces propriétés directement dans les fichiers sources.

En revanche, leur portée est au niveau fichier, et non générateur

Les mêmes propriétés pourront également être passées dans la ligne de commande.

Ligne de commande

asciidoctor-pdf --theme pdf -a pdf-themesdir=.asciidoctor docs-as-code-03-styles.adoc

L'exécutable est bien ici asciidoctor-pdf et non asciidoctor

Libérer votre créativité

Si la génération HTML offre de plus larges possibilités en matière de personnalisation de visuel, il semble intéressant de ne pas oublier les possibilités offertes par asciidoctor-pdf⁵.

D'un côté, la configuration dans des formats paginés à destination de l'impression demande une maîtrise particulière des différents attributs offerts par les outils.
Heureusement, leur documentation dense décrit les possibilités du plugin.
Il sera nécessaire de la parcourir afin d'obtenir le rendu souhaité.

De l'autre côté, l'écosystème HTML⁴/CSS³ permet de revenir dans un monde qui nous est peut-être plus proche : celui du développement.
Toutefois, les limites posées par la sémantique HTML proposée par asciidoctor apportent des contraintes qui peuvent s'avérer limitantes.
La prise de connaissance des subtilités de ces outils est chronophage, et vous risquez malgré tout de ne pas atteindre le résultat attendu.

Comme je vous l'ai montré dans l'article précédent, il existe un outil d'agrégation de documentation appelé Antora.
Cet outil, même s'il est basé sur Asciidoctor, utilise un moteur de templating plus complexe.

Et si les compétences en HTML/CSS peuvent rapidement être le facteur limitant de nos générations basiques, il en existe d'autres si vous utilisez Antora.
Mais ceci est une autre histoire...

Doc as code, un parcours initiatique pour publier !

Nicolas Giraud — Tue, 13 Feb 2024 10:23:00 +0000

Écrire des fichiers en doc as code pour produire des notes ou des compte-rendus est relativement simple.
Construire une documentation collaborative, partagée et versionnée, c'est une autre histoire.
Et au-delà des considérations techniques, vos process de publication peuvent apporter une complexité supplémentaire...

Vous avez probablement fait vos premiers pas en doc as code. Non ?
Repartez des bases avec ce petit guide illustré pour mieux se lancer, un article pour vous montrer comment produire un document manuellement.

Ce n'est clairement pas suffisant dans un contexte de travail en équipe, et je vous propose de regarder cela d'un peu plus près.
Après avoir parlé processus et fait un tour du côté d'Asciidoctor¹, je vous emmène à la découverte d'Antora², l'outil qui m'a changé la vie !

Cette version de l'article a été publiée avec la chaîne de publication de l'écosystème Asciidoc³.

Écrire en équipe, une collaboration saine et sereine.

Vous avez appréhendé la production de fichier texte dans vos premiers documents, à l'image des fichiers source de vos applications.
Au-delà de se concentrer sur le contenu, vous allez pouvoir reprendre les pratiques de développement en vigueur sur votre projet.

Ainsi, en déversant vos documents dans un dépôt Git⁴ vous pourrez profiter des fonctionnalités d'historisation et de relecture d'un tel outil.
Se présente alors devant vous l'ère de la rédaction collaborative !

Vous pouvez observer ci-dessus l'historique de la production des documents, d'abord dans un contexte solitaire, puis dans l'ajout collaboratif de deux documents A et B.

B étant prêt en premier, il intègre la documentation avant A, dont la revue prend plus de temps.

Si la représentation des contributions ici est simple, il met en avant la possibilité de définir un processus de revue et de publication à base de l'outillage standard de développement.

Je vous invite à prendre soin de cette phase de définition du processus.

À priori simple, elle renferme des questions de gouvernance qui sont souvent primordiales à la bonne contribution de chacun.

Maintenant que vous avez le concept, passons aux techniques de publication !

Classer et hiérarchiser : comment générer toute une arborescence.

Les documents se multipliant, vous avez sans aucun doute commencé à les découper, les classer et pourquoi pas les hiérarchiser.
À ce stade, vous n'imaginez plus les générer un par un à la main !
Et c'est une bonne chose...

Asciidoctor¹ est le seul outil de génération dans l'écosystème Asciidoc.
En tout cas, il est la base sur laquelle se reposent tous les outils que nous avons déjà vus et que nous verrons plus loin.
Il est, par exemple, derrière le plugin chrome présenté dans l'article précédent
Il permet de prendre une source et de la convertir dans un ou plusieurs formats de sortie.

Précédemment, je vous ai parlé de partager vos sources à l'aide de Git⁴.
Dans la continuité, voici comment avec Asciidoctor¹ et Gitlab³, plus précisément de ses deux fonctions CI⁵ et pages⁶, vous allez pouvoir en quelques lignes produire une documentation.

Je vous propose de commencer par écrire un petit script pour générer vos documents.
Pour cela, prenez un projet avec la structure suivante.

Pour générer les fichiers, vous pouvez passer une commande proche de celle-ci :

asciidoctor \
    -R doc-as-code \            #<1>
    -D public \                 #<2>
    'doc-as-code/**/*.adoc'     #<3>

Répertoire racine des sources asciidoc. Permet de conserver l'arborescence dans le répertoire cible.
Répertoire de sortie des fichiers générés
Expression régulière pour trouver les fichiers à générer

Je vous invite à regarder les différentes options présentes dans la documentation de la CLI d'Asciidoctor¹ afin de générer un résultat correspondent à vos attentes.

Une fois la commande prête, je vous propose de l'utiliser avec Gitlab-CI⁵.

pages:
  stage: deploy
  image: asciidoctor/docker-asciidoctor                            #<1>
  script:
    - asciidoctor -R doc-as-code -D public 'doc-as-code/**/*.adoc' #<2>
  artifacts:
    paths:
    - public                                                       #<3>
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH                  #<4>

Se base sur l'image Docker de Asciidoctor
La commande qui génère les fichiers statiques
Permet de demander à Gitlab de conserver les fichiers générés et de les exposer avec sa fonction pages
Ne s'exécute que sur la branche principale (main par défaut)

Il vous reste à configurer votre projet pour activer Gitlab Pages, et vos documents seront partagés !
Pour cela je vous invite à consulter la documentation de Gitlab.

Passez à la vitesse supérieure : agréger et versionner plusieurs dépôts.

À ce stade, votre équipe est en capacité de produire une documentation à partir d'un dépôt de source et de la mettre à disposition de ses lecteurs.
Mais votre produit a plusieurs composants, répartis dans différents dépôts Git⁴.

Et le nombre de solutions pour agréger vos contenus n'a de limite que votre imagination...
Pour que votre créativité reste à sa place, je vais vous parler ici d'un produit en particulier : Antora².

Cet outil, intégrant directement l'écosystème Asciidoc⁷ va vous permettre de produire un site statique en assemblant les documentations de vos différents composants (alias dépôt Git⁴).

Il vous faudra un dépôt qui contiendra un playbook définissant le contenu du site à générer et une structure particulière dans vos dépôts.

Le playbook peut être contenu dans votre composant principal. Dans ce cas la séparation des responsabilités n'est pas pleinement respecté, mais peut simplifier votre agrégation

Voici le playbook:

site:
  title: Vos projets
  start_page: votre-projet::index.adoc
content:
  sources:
  - url: https://votre-gitlab.com/votre/groupe/votre-projet.git   #<1>
    branches: develop                                             #<2>
    start_path: docs                                              #<3>
  - url: https://votre-gitlab.com/votre/groupe/votre-super-projet.git
    branches: [2.0, 1.0]                                          #<4>

URL du dépôt git du composant.
Noms des branches où trouver la doc à générer
Chemin relatif de l'emplacement du fichier antora.yml
Plusieurs branches => plusieurs versions de la documentation.

Vous avez ici la possibilité d'indiquer à Antora de générer plusieurs versions de votre documentation pour un même composant.

Cette fonctionnalité se repose sur des tags ou des branches positionnées dans vos dépôts.

Coté projet, vous devrez écrire un fichier de configuration et à réorganiser vos fichiers⁸.

Antora ajoute une notion de module particulièrement pratique pour regrouper vos documents par catégorie.

Cependant, je vous déconseille de l'utiliser au départ.
Laisser vous le temps de vous familiariser avec l'organisation des sources dans Antora.

name: votre-projet            #<1>
version: current              #<2>
title: Votre projet           #<3>
nav:
- modules/ROOT/nav-begin.adoc #<4>
- modules/ROOT/nav-end.adoc

Clé du projet utilisée pour les liens
Nom de la version qui sera générée (doit changer pour chaque branche générée.)
Nom du projet
Lien vers les fichiers de navigation utilisés pour la construction du menu

Les fichiers de navigation doivent être écrits manuellement.

Alors, prêts à produire votre documentation ?

Avec Asciidoctor¹ et Antora², vous l'avez compris, nous n'avons fait que survoler deux outils d'un écosystème dense.

La configuration et la mise en place de ces outils vous demanderont un peu d'effort et surtout la lecture de la documentation de chacun de ces outils.
Il faut d'ailleurs noter la bonne qualité de ces documentations, ce qui est rassurant pour des outils censés vous aider à produire la vôtre !

Quoi qu'il en soit, et pour faire une nouvelle fois un rappel à l'article précédent : Keep It Simple Stupid⁹ !
Cet adage reste essentiel, autant dans les processus mis en place, que dans les outils mis en œuvre.

Cependant, la sobriété des rendus générés peut donner à vos documents un aspect côté impersonnel.
Pour palier cela, moyennant un peu de code, vous pouvez personnaliser les designs de sortie, mais ceci est une autre histoire...

Doc as code, petit guide illustré pour mieux se lancer

Nicolas Giraud — Thu, 01 Feb 2024 10:23:00 +0000

En tant que développeurs et développeuses, notre environnement de développement est notre outil principal.
Vous avez sans doute, comme moi, rencontrez des difficultés dans la manipulation de documents de type bureautique.
Ajouter des extraits de code, récupérer une commande formatée, sont de tristes expériences qui vont vous attirer vers la doc as code.

Le premier principe qui va nous intéresser est de pouvoir nous concentrer sur le fond des documents à produire, et non sur leur forme.
Évidemment cette dernière reste importante, et nous allons y revenir.
Mais, rester focalisé sur le contenu, en apportant des indicateurs simples, est réellement confortable. Un confort qui s'illustre rapidement dans la mise en évidence de certaines idées, ou l'emphase de portions de texte particulières comme du code.

En complément, si vous êtes habitués des outils du web, que ce soit des forums, des encyclopédies (type Wikipédia¹), vous pratiquez déjà probablement ce type d’écriture à balisage faible. Il en existe d’autres, mais nous ne citerons ici que Markdown², ou Asciidoc³ qui sont utilisés dans de nombreux projets informatiques.

De mon côté, je suis tombé dans Asciidoc³. Sans considérer que cette syntaxe soit meilleure, j’y trouve une plus grande cohérence et un balisage faible permettant de conserver la lisibilité du texte brut⁴. Les outils qui vont suivre sont issus de cet écosystème, même si des équivalents existent.

Vous pourrez jauger de ces différences entre Markdown² et Asciidoc³ dans cette version, de l'article au le format Asciidoc³.

Écrire : n'est-ce pas la base ?

Derrière nos outils parfois complexes, je vous invite à vous concentrer sur l'essentiel : écrire.
Et croyez-moi, faire simple, est parfois compliqué !

Malgré la nécessité d'écrire, le balisage léger de Asciidoc³ va apporter immédiatement de la structuration.
Il vous sera alors possible, tout en restant focalisé sur ce que vous écrivez, d'organiser toutes vos idées par chapitres, par listes, ou éventuellement par tableaux.
Des = pour les niveaux de titre, quelques * ou . pour gérer vos listes, et le tour est joué.

Et tout comme votre code, vous pourrez découper vos productions en différents fichiers. Il sera ensuite aisé d'inclure tout ou partie de ces notes, toujours grâce aux syntaxes d'Asciidoc³, même si cette fois, elles sont moins légères.

Consultez la documentation Asciidoc³ pour connaître les différentes possibilités de cette syntaxe.

Sachez qu'il existe dans tous nos IDE des plugins pour permettre un rendu au fil de l'eau de ce que vous écrivez.
Ce sera là votre premier outil et voici à quoi cela peut ressembler :

Remarquez ici l'inclusion d'une image.
Il peut s'agir d'une des premières difficultés.

Si vous avez besoin d'insérer des illustrations, vous devrez les gérer en externe et les inclure à vos écrits.
La manipulation de ces images, en positionnement, en taille, ou pour les amender ne sera pas possible facilement dans l'outil de doc as code

Ces syntaxes n'évitent pas des travers habituels de notre métier.
Rapidement, nous arrivons à produire des systèmes complexes difficiles à prendre en main.
Il sera alors indispensable de se recentrer sur les basiques : écrire, organiser ses idées, rendre une mise en page simple, mais fluide.

En un mot, comme dans notre code applicatif : Keep It Simple Stupid, KISS⁵ pour les intimes !

Partager vos documents : comment aller à l'essentiel ?

Ecrire, c'est bien, mais partager c'est encore mieux !
À ce stade, je vous ai montré comment produire des documents simples et visualiser le rendu en direct. Découvrons ensemble quelques astuces pour collaborer et partager simplement vos réalisations

L'outil collaboratif par excellence du monde du développement est sans aucun doute Git.
Accompagné de ses gestionnaires de dépôt (Gitlab, Github, etc.), vous pourrez mettre en place des processus de relecture et de validation bien connus de vos équipes.

Si toutefois ces pratiques ne vous sont pas familières, utilisez ces outils localement.
Il vous faudra alors générer localement les documents pour pouvoir les partager.

Côté génération, un premier outil intéressant et dont tout le monde dispose, est votre navigateur.
Ce dernier met à disposition des plugins qui vont vous permettre un premier rendu de vos écrits.
Utilisez ensuite la fonction imprimer de votre navigateur, et hop, vous avez un format PDF partageable.

Pour des générations plus automatisées ou systématisées, il faudra mettre en place une chaine de publication.

Vous rencontrerez alors votre seconde difficulté : la mise en place de ce type de chaine.
C'est naturel lorsque vous généralisez ces pratiques sur une équipe ou plus !

Si toutefois vous préférez un format orienté web, il existe des outils de conversion en HTML.
Dans l'écosystème Asciidoc³, on peut citer Asciidoctor⁶, ou encore Antora⁷:.

L'usage de ces produits nécessite l'utilisation de processus plus ou moins automatisé et d'une gestion des sources avancée.

Coté design, ils sont souvent assez épurés. Ils permettent cependant une mise en forme simple et efficace.

Vous constatez que suivre notre mantra KISS⁵ est plus difficile lorsqu'on parle de partage et de publication.

Se limiter à son navigateur est possible.
Mais si vous tombez amoureux de ces outils vous devrez rapidement passer à la vitesse supérieure.

Alors, quand est-ce que vous vous y mettez ?

La simplicité est indispensable lorsque l'on débute en doc as code.

La fluidité de l'écriture au kilomètre et la structuration de vos idées au fil de l'eau sont l'atout essentiel de ces pratiques.
Par expérience, ils nous apportent un confort mental incroyable au moment de la rédaction en déversant le flots des idées dans des fichiers simples à relire.

Mais l'appropriation des outils de doc as code n'est pas toujours un long fleuve tranquille...
Vous y lancer changera forcément votre approche des supports écrits, mais n'oubliez pas d'emprunter ce chemin étape par étape.
Cela peut être, par exemple, en commençant par la prise de notes, puis la rédaction de document, pour aller jusqu'aux illustrations...

Vous risquez cependant d'avoir besoin dès vos premières publications de personnaliser vos rendus.
Charte à suivre ou simple envie d'esthétisme, vous aurez besoin de compétences et de temps.

Mais ceci est une autre histoire...