AsciiDoc : documentation as code

Rédigé le 13 juin 2018
par Jean-Michel Doudoux
dans Autres

AsciiDoc est un format textuel qui permet d’écrire des documents (livres, ebooks, articles, pages web, blogs, …). Il est particulièrement pratique pour les documentations techniques.

AsciiDoc propose un langage textuel. L’utilisation d’un format textuel a plusieurs avantages :

l’édition ne nécessite pas d’outil particulier : un simple éditeur de texte suffit
le document est ainsi facilement lisible et modifiable
deux versions d’un document sont très facilement comparables
la taille des documents est très légère

Pour améliorer la productivité de la rédaction d’un document AsciiDoc, il est possible d’utiliser des outils qui prévisualisent le rendu du document et assure une coloration syntaxique. Cela permet de rapidement corriger les erreurs de syntaxe.

L’outil AsciiDoctor et son écosystème sont utilisés pour transformer un document AsciiDoc afin de générer des documents dans différents formats publiables (HTML, DocBook, PDF, ePub, …).

La définition d’un document

Les fichiers AsciiDoc ont généralement l’extension .adoc.
Un document AsciiDoc est un fichier texte qui débute par des informations générales (titre du document, auteur(s), versions) et des attributs :

= Titre du document
Nom de l’auteur <auteur@oxiane.com>
v1.0, 2018-06-11
:toc:
:imagesdir: images

AsciiDoc prédéfinit de nombreux attributs qu’il va utiliser pour sa configuration. Il est aussi possible de définir ses propres attributs. Dans tous les cas, la valeur d’un attribut s’obtient avec la syntaxe suivante :

{nom_attribut}

Il est possible d’inclure des fichiers dans un fichier AsciiDoc en utilisant la macro include

include::chapitre_01.adoc[]

Le formatage du texte

Le texte est organisé en paragraphe : il n’y a pas de syntaxe particulière pour les délimiter. Les lignes de texte adjacentes ou consécutives forment un paragraphe. Pour en commencer un nouveau après un autre élément il suffit d’utiliser une ligne vide.

Un retour chariot n’apparait pas dans les documents générés. Il est possible de forcer un retour chariot à la fin d’une phrase en utilisant un espace suivi du caractère plus.

Exemple de code :

Première ligne du paragraphe.
Elle se poursuit avec une seconde ligne qui fait elle même partie du paragraphe

Texte avec saut de ligne force +
Ligne suivante

Exemple de rendu :

Une barre de séparation horizontale est définie en utilisant

'''

Il est possible de demander un saut de page en utilisant

<<<

Une syntaxe particulière permet de formater du texte

Exemple de code :

normal

_italique_

*gras*

+mono+

''double quote''

'simple quote'

E=mc^2^

H~2~O

Exemple de rendu :

Les commentaires sur une ligne commencent par un //

// commentaire

Plusieurs séquences sont remplacées par des caractères Unicode particuliers

Exemple de code :

(C)  (TM)  ->  <-  =>  <=  ...  &#8364;

Exemple de rendu :

L’échappement des caractères spécifiques peut se faire de deux manières :

\*gras*

+++*gras*+++

Les titres des sections

AsciiDoc propose plusieurs formats pour les titres des sections :

Asymetric atx-style : c’est le style recommandé car c’est le plus simple à mettre en œuvre. Défini sur une seule ligne, le titre est précédé d’un ou plusieurs caractères = qui indique le niveau de la section

= Titre du document
== sous-titre niveau 1
=== sous-titre niveau 2
==== sous-titre niveau 3
===== sous-titre niveau 4
====== sous-titre niveau 5

Symetric atx-style : il s’utilise comme le style Asymetric atx-style mais il impose en plus de terminer le titre par la séquence de délimitation

== sous-titre niveau 1 ==

Setext-style : c’est le style historique qui définit le titre sur deux lignes. La première contient le titre et la seconde est un ensemble d’un caractère répété pour souligner le titre. Chaque niveau est défini grâce à un caractère particulier : =, -, ~, ^, et +. L’utilisation de ce style n’est plus recommandé.

Titre du document
=================
sous-titre niveau 1
-------------------

Les listes

Plusieurs types de liste sont supportés par AsciiDoc. Chaque liste peut avoir un titre optionnel défini avec le caractère .

Les listes non ordonnées

Elles sont définies avec le caractère *

Exemple de code :

.Les formats supportés
* XML
* JSON
* YAML

Exemple de rendu :

Les listes peuvent imbriquer différents niveaux simplement en utilisant autant de caractères * que le niveau souhaité.

Exemple de code :

* Technologies front 
** JavaScript
** CSS
* Technologies back
** Java
** Node JS

Exemple de rendu :

Les listes ordonnées
Elles sont définies avec le caractère . suivi d’un espace et supportent aussi le multi-niveau

Exemple de code :

.Les éléments ordonnés sont :
. élément 1
. élément 2
.. élément 21
.. élément 22
. élément 3

Exemple de rendu :

Les listes avec étiquettes

Elles sont définies en séparant l’étiquette et la définition avec ::

Par défaut, le rendu se fait sur deux lignes : la première contient l’étiquette et la seconde la description

Exemple de code :

.Type de mémoire
RAM:: Random Access Memory
ROM:: Read Only Memory
NVRAM:: Non volatile random access memory

Exemple de rendu :

Il est possible de demander le formatage sur une seule ligne

Exemple de code :

[horizontal]
.Type de mémoire
RAM:: Random Access Memory
ROM:: Read Only Memory
NVRAM:: Non volatile random access memory

Exemple de rendu :

Les checklists
Elles sont définies avec un tiret suivi d’une paire de crochet qui précise l’état de la tâche. Une étoile ou un x sont utilisés pour indiquer que c’est coché.

Exemple de code :

. Tâches à faire
- [*] Tache 1
- [x] Tache 2
- [ ] Tache 3
- [ ] Tache 4

Exemple de rendu :

Les liens

AsciiDoc reconnait automatiquement les liens vers :

http
https
ftp
irc
mailto
email@oxiane.com

Il est possible de préciser le libellé du lien entre crochets :

http://www.oxiane.com[Site Oxiane]

Les blocs

Les blocs permettent de structurer du texte qui ne sont pas des paragraphes.

Différents types de blocs sont utilisables. Ils se définissent avec une suite d’au moins quatre caractères selon leur type et se terminent avec la même suite de caractères. Il est recommandé de n’utiliser que quatre caractères.

Séquence de caractères	Rôle
----	Bloc permettant de délimiter un contenu généralement pour du code source
////	Bloc de commentaires
....	Bloc littéral : restitue le texte tel qu’il est fourni
====	Bloc exemple
****	Bloc de type sidebar : le contenu est restitué en dehors du flux
____	Bloc de type citation ou verset

Exemple de code :

Exemple de rendu :

Les tableaux

Un tableau est défini comme un bloc particulier avec la séquence |===

Chaque cellule du tableau est définie avec un caractère |

Exemple de code :

|===
|Firefox
|Chrome
|Safari
|===

Exemple de rendu :

Par défaut, le nombre de colonnes est déterminé par la première ligne qui suit le délimiteur de tableau.

Exemple de code :

|===
|Browser |Version
|Firefox
|60
|Chrome
|66
|Safari
|11
|===

Exemple de rendu :

Il est possible de préciser explicitement le nombre de colonnes

Exemple de code :

[cols=2]
|===
|Browser
|Version
|Firefox
|60
|Chrome
|66
|Safari
|11
|===

Exemple de rendu :

La configuration d’un tableau peut être très pointues avec une syntaxe dédiée.

Exemple de code :

[%header%footer,cols="2,2s,3",grid=rows,frame=topbot,width=100%,caption=Organisation]
|===
|Nom |Fonction |Twitter

|D Martin
^m|PDG
|mailto:dmartin@societe.fr[dmartin@societe.fr]

|JF Dupond
^m|DG
|mailto:jfdupond[jfdupond@societe.fr]

3+^.e|Les dirigeants
|===

Exemple de rendu :

Il est aussi possible de créer facilement un tableau en utilisant des données au format CSV

Exemple de code :

[%header,format=csv]
|===
Nom,Type,Description
Java,Langage,Langage de programmation polyvalent
Linux,Système d'exploitation,OS libre de type Unix
Apache,Serveur,Serveur web
|===

Exemple de rendu :

Les images

Il est possible d’ajouter des images en utilisant la syntaxe image:: suivi du chemin de l’image puis d’une paire de crochets qui peut contenir un texte alternatif.

image::logo_oxiane.jpg[Logo Oxiane]

Le chemin est relatif par rapport à l’attribut imagesdir du document

Le code source

AsciiDoc permet d’intégrer du code source dans le document. AsciiDoctor supporte plusieurs outils de coloration syntaxique qui pourront améliorer la lisibilité du code dans les documents générés.

Exemple de code :

.Exemple 1
[ source,java]
----
public class HelloWorld {
  public static void main(String[] args) {
    System.out.println("Hello world");
  }
}
----

Exemple de rendu :

Il est possible d’inclure un fichier contenant le code source.

[ source,java]
----
include::HelloWorld.java[]
----

Il est aussi très pratique d’indiquer des renvois numérotés pour commenter le code.

Exemple de code :

.Exemple 3
[ source,java,numbered]
----
public interface Affichage { // # 
  void afficher(); // # 
} // # 
----
 déclaration de l'interface
 déclaration de la méthode public abstract
 fin de la déclaration

Exemple de rendu :

Plusieurs autres syntaxes sont aussi supportées :

Exemple de code :

.Exemple 4 XML
[ source,xml]
----
<auteur id="1">
  <personne>
    <nom>Martin</nom>
    <prenom>Pierre</prenom>
  </personne>
</auteur>
----

Exemple de rendu :

Les diagrammes UML

AsciiDoctor Diagram est un ensemble d’extensions AsciiDoctor pour générer des diagrammes à partir d’une description textuelle qui seront inclus dans les documents générés. De nombreux formats sont supportés : AsciiToSVG, BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag), Ditaa, Erd, GraphViz, Mermaid, Msc, PlantUML, Shaape, SvgBob, Syntrax, UMLet, Vega, Vega-Lite et WaveDrom. Il est ainsi possible de définir un diagramme de classes par exemple avec PlantUML.

Exemple de code :

[ plantuml, diagram-classes, png]
....
interface Interface

class Mere << general >> {
{static}-champ1
#champ2
{abstract}~methode1()
+methode2()
}
class Fille1
class Fille2

Interface <|-- Mere
Mere <|-- Fille1
Mere <|-- Fille2

note "mon commentaire" as N1

....

Exemple de rendu :

Un autre exemple avec un diagramme de séquence

Exemple de code :

[ plantuml]
----
IHM -> Service : getData
Service <->  DAO : save
----

Exemple de rendu :

Les admonitions

Elles permettent d’attirer l’attention sur certaines informations avec un niveau de priorité défini grâce à une étiquette en majuscules :

NOTE (remarque),
TIP (conseil),
IMPORTANT,
CAUTION (avertissement),
WARNING (attention)

Exemple de code :

WARNING: Son utilisation en production n'est pas recommandée.

Exemple de rendu :

Conclusion

Cet article n’est qu’une introduction aux fonctionnalités de base d’AsciiDoc qui propose par ailleurs de nombreuses fonctionnalités avancées comme la génération d’une table de matière ou d’un index, des notes de bas de pages (foot notes), …

Les fonctionnalités sont aussi accrues grâce au support de nombreux outils tel que la génération de diagrammes, syntax highlighter (Rouge, Pigment, …)

Le rendu de nombreux éléments peut aussi être personnalisés. AsciiDoctor s’intègre aussi parfaitement avec une solution d’intégration continue.

AsciiDoc connait un succès grandissant comme en témoigne la richesse de son écosystème.

Post Tags - AsciiDoc, Documentation

Facebook

Twitter

Viadeo

Written by Jean-Michel Doudoux

CTO OXiane

Julien Poyard

super article, merci!
cheroliv

Merci pour cet article en français et très propre.
Mohamed Romdhani

Parfait

Blog

AsciiDoc : documentation as code

La définition d’un document

Le formatage du texte

Les titres des sections

Les listes

Les liens

Les blocs

Les tableaux

Les images

Le code source

Les diagrammes UML

Les admonitions

Conclusion

Written by Jean-Michel Doudoux