DocGen Next

DocGen vous proposes un cadre d'écriture documentaire, tous vos projets seront organisés de la même façon, les outils nécessaires à l'écriture et dessins de diagramme sont installés et configurés. Vous n'avez plus qu'à vous lancer dans l'écriture sans vous souciez du reste.

Cet outil vous permet de créer des documentations au format HTML, PDF, docbook et Word, il repose principalement sur Asciidoctor.js.

Pré-requis

‼️ : deux outils sont nécessaires pour utiliser DocGen Next :

1. Node (v12.16.3 minimum)
2. git

Optionnel : vous pouvez installer Pandoc pour convertir des fichiers sur d'autres formats.

Installer DocGen Next

Lancer la commande suivante dans un Terminal :

npm i -g docgennext

Initialisation d'un projet documentaire

Une fois les étapes précédentes réalisées, lancer la commande suivante :

docgen

Une série de questions vous seront posées, elles permettent de configurer le projet en fonction de vos réponses.

Arguments

Il est possible de passer outre les questions, notamment quand vous voulez automatiser un flux de production documentaire.

Pour cela rien de plus simple, renseigner chaque question par son identifiant, par exemple :

docgen --author 'Laurent Dupont' --email [e-mail]

Voici la liste des identifiants disponibles (liste complète) :

Identifiant	Exemple	Type	Requis
title	--title 'ma documentation'	string	✔️
lang	--lang 1	number	✔️
author	--author 'Laurent Dupont'	string	✔️
email	--email [e-mail]	string
description	--description 'La description de ma doc.'	string	✔️
versionDoc	--versionDoc '3.2.1'	string
port	--port 4545	number
kroki	--kroki http://197.129.7.12:3591	string
confirm	--no-autolaunch	boolean

Les valeurs suivantes sont par défaut initialisées à :

Identifiant	Valeur par défaut	Signification
lang	0	Par défaut la valeur est 0 pour fr.
version	'0.1.0'	Version de votre documentation.
port	8080	Port du serveur localhost.
kroki	https://kroki.io/	Serveur Kroki.
confirm	true	Lance le serveur automatiquement.

Le choix de la langue est réalisé par un number. La valeur 0 équivaut à fr, dans le cas contraire à en.

La version suit la Gestion sémantique de version 2.0.0.

‼️ : afin d'indiquer un numéro de version, utiliser bien une chaîne de caractères, c'est à dire avec des guillemets pour éviter tout problème d'interprétation.

Le paramètre title est utilisé à la fois pour la clé name du fichier package.json et pour le titre de la documentation.

Pour les DevOps, utilisez le flag --no-autolaunch si vous ne souhaitez pas générer la documentation dans un navigateur après avoir alimenté toutes les questions. Si il est nécessaire d'ouvrir votre navigateur, utilisez le flag --autolaunch.

Les auteurs

Dans le cas où plusieurs personnes participent à l'écriture du document, une liste de personnes peut être indiquée. Dans ce cas veuillez utiliser cette forme :

docgen --author "Alex Mitch, Paul Richard, François Rich"

‼️ : liste de prénoms, séparé par des virgules.

Port du serveur

Une fois le projet créé, il est possible d'exécuter une commande pour afficher les résultats de votre documentation dans une page Web. Votre navigateur par défaut est lancé et se rafraichit automatiquement pour vous montrer les derniers éléments modifiés.

Il peut être important de changer cette valeur quand vous travaillez sur plusieurs documents en parallèle.

❗ : prévilégiez les valeurs comprises entre 1001 & 9999.

Kroki

Le serveur Kroki permet de générer tout un ensemble de diagrammes écrit au format texte. Par défaut c'est le serveur disponible sur Internet qui est utilisé. Vous pouvez changer cette valeur pour utiliser le votre.

Organisation d'un projet documentaire

Une fois répondu aux questions, vous allez avoir l'organisation suivante :

Concentrez votre attention sur le dossier project/. Il est proposé de créer un ensemble de sous-dossiers, chacun représentant une section de votre documentation. Dans chacun de ces dossiers vous y placerez les paragraphes constituant chacune des parties. Le fichier main.adoc doit intégrer uniquement les imports des fichiers de votre documentation.

Structure des fichiers

Le projet se décompose ainsi :

• .editorconfig : installez un plugin editorconfig dans votre IDE si besoin,
• .git/ et le fichier .gitignore pour la gestion des sources,
• node_modules : contenant tous les paquets node,
• package.json et package-lock.json : que nous verrons plus tard,
• project/ dont on vient de parler,

Personnalisation de votre documentation

Asciidoctor.js met à disposition un ensemble d'éléments pour que vous modifiez votre documentation comme vous le souhaitez. Fichiers CSS, templating, hooks, etc. Référez-vous à la documentation officielle du projet.

Vous pouvez facilement ajouter des fichiers, sans modification de la configuration :

• project/docinfo/ : pour les fichiers docinfo.html et docinfo-footer.html.
• project/icons/ : emplacement de vos icones.
• project/images/ : pour toutes vos images raw (png, jpg, gif).
• project/styles/ : mettez ici tous vos fichiers CSS.
• project/templates/ pour y sauvegarder vos fichiers templates (le langage de template par défaut est Nunjucks mais rien ne vous empêche d'en installer d'autres).

Deux fichiers importants :

• project/confadoc.adoc : pour configurer votre projet avec les variables Asciidoctor.
• project/variables.adoc : renseignez les variables de votre documentations (références externes par exemple).

Font Awesome

Si vous souhaitez utiliser des icônes, reportez-vous à la documentation de Asciidoctor. Les Font Awesome 5 arriveront plus tard, dans tous les cas, aujourd'hui DocGen Next ne porte pas ce sujet.

Concernant le PDF, les Font Awesome 5 sont déjà présentes.

Styles

Afin de personnaliser vos documents, il est nécessaire de créer un ou plusieurs fichiers dans le dossier styles.

Dans le fichier project/confadoc.adoc, ajoutez la ligne suivante : :stylesheet: ./styles/styles.css.

Lors de l'affichage dans le navigateur web, si vous avez des erreurs concernant le Cross origin, désactivez-les.

IDE

N'importe quel éditeur de texte fera l'affaire, les deux éditeurs les plus adaptés sont :

• Sublime Text
• Visual Studio Code
• Ou son fork qui ne récupère pas les données statistiques VSCodium

Extensions

Un certains nombres d'extensions sont disponibles pour vous donner plus de contrôle lors de l'écriture de vos documents.

### Couleurs

Vous pouvez indiquer un nom d'une couleur du web, du RGB, RGBA, HSL, HSLA ou HEX, par exemple :

color:#FF5733[]

Plus d'informations : https://github.com/Mogztter/asciidoctor-color

### Emoji

Pour intégrer des émoticons dans vos documents :

emoji:wink[]

Il est possible d'indiquer une taille plus grande ou directement en pixel dans les crochets.

Plus d'informations : https://github.com/Mogztter/asciidoctor-emoji

Livrables

Vous trouverez ici les différentes instructions pour générer les formats proposés par Asciidoctor.

HTML

Pour compiler la documentation et générer le fichier HTML :

node index.js

Un dossier build est créé à la racine du projet s'il n'existe pas et le fichier index.html est compilé.

Avec la commande suivante :

npm start

Le navigateur par défaut du système d'exploitation est ouvert et la page affichée.

Toute modification ou fichier copié dans le dossier project génère une recompilation de la documentation et la page dans le navigateur est mise à jour.

PDF

Pour générer le fichier PDF, entrez la commande suivante dans un Terminal :

npm run pdf

Si vous souhaitez modifier la mise en page de vos documents PDF, une lecture de Pagedjs est nécessaire.

La lecture de la documentation asciidoctor.js est recommandée.

En fonction de vos besoins, modifiez ou ajoutez dans la partie scripts du fichier package.json de nouvelles commandes.

Docbook

Pour générer un fichier XML, utilisez la commande suivante :

npm run docbook

Un fichier book.xml sera généré dans le dossier build.

Word

Il est nécessaire d'installer Pandoc pour transformer un fichier XML en fichier Word (.docx).

Après avoir utilisé la commande précédente, vous pouvez utiliser la commande suivante pour générer un fichier Word :

npm run pandoc

Si vous souhaitez générer un fichier XML, suivi du fichier Word, utilisez la commande suivante :

npm run word

Contribuer

Toute personne souhaitant participer au projet, pour l'améliorer ou proposer des évolutions est bienvenue.

Licence

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.