CI/CD pour la documentation

J’ai récemment fait une présentation pendant “All Day DevOps” au côté de Laurent Gil sur CI et CD pour la documentation.
Le replay est ici et les diapos ici (sur GitHub, avec des GitHub actions pour illustrer le propos).

CI CD pour la doc

Et vous, vous pratiquez ? Parceque nous, on est fans :star_struck:

4 J'aime

Bonjour @ojacques

Je suis moi aussi en plein dans cette démarche d’industrialisation de la documentation.
L’idée étant d’avoir à un seul endroit toute la documentation au format markdown et qu’elle soit facilement maintenable dans le temps.
Pour ma part j’utilise le générateur de site statique vuepress et je m’intéresse aussi au thème mrhope qui semble ajouter plein de features sympa comme la gestion de slides, la génération de workflow, … le tout en markdown.

Un avis sur ces technos ?

Bonne journée,

Benjamin

3 J'aime

J’utilise principalement mkdocs, avec le thème material.

Pour les sites très “fancy”, j’utilise Hugo.

J’aime bien mkdocs parceque:

  • Le markdown / la doc reste lisible sur GitHub / GitLab
  • mkdocs reste assez simple à installer sur tout type de plateforme (Linux, Windows ou WSL)
  • Il y a une tonne de plugins qui peuvent couvrir des cas d’utilisations vraiment compliqués (eg générer des PDF avec weasyprint stylés avec du CSS, arranger l’ordre des pages, cacher des arborescences, …)

J’avais entendu parler de Vuepress, mais pas vraiment regardé encore.

3 J'aime

J’utilise hugo avec un theme particulier pour gerer une arborescence. Par contre les collègues sont pas convaincus :cry: (mais on vient de loin, migration cvs git il y a peu)

1 J'aime

Bonjour

J’utilise lektor pour générer mon site web à partir de la CI de gitlab. Ca permet d’écrire le site en markdown.

Mais, depuis, j’ai découvert org-mode qui permet de générer du markdown (et plein d’autres formats: reveal.js word, html, gfm). Je n’utilise plus que ce format pour écrire de la doc ou des présentations. Un jour, je convertirai mon site en org-mode…

2 J'aime

Je trouve Hugo vraiment top quand il faut faire de gros sites, de type “marketing” où le format est prépondérant. Mais pour la doc technique, je préfère mkdocs pour sa simplicité et les possibilités d’extension qui m’ont toujours permis de répondre aux différentes situations.

Pour ceux qui ont connu Jekyll: j’ai arrêté à cause de sa lourdeur et la difficulté de faire tourner les sites sur les postes de tous (Windows !).

Je suis fan!
J’ai découvert avec GitLab et depuis septembre mon nouvel employeur utilise Confluence, et franchement, c’est la déprim :disappointed_relieved:

J’en parle dans mon Meetup Virtuel d’octobre #autopromo

J’ai testé lektor, pour sa promesse de «mise a jour faisable par un non-tech» (pas de git et wysiwyg), mais je l’ai trouvé plus lourd a mettre en place que pelican, et a forciori mkdocs.
Qu’est ce qui t’as motivé?
As-tu pu mettre du lektor dans des main non-tech?

Qu’est ce qui t’as motivé?

J’ai essayé plusieurs générateurs sans trop comprendre comment faire. lektor est le premier qui m’a permis de sortir quelque chose de correct sans que j’y passe trop de temps,

Cerise sur le gâteau: lektor est disponible sur ma machine Debian avec “apt get”. Les mises à jour sont donc très faciles.

As-tu pu mettre du lektor dans des main non-tech?

Non, je n’ai pas essayé

HTH

Et bien pour ma part : mkdocs et certains outils de générations de doc d’API comme Swagger UI, le tout propulsé par Gitlab Pages.

Par contre, beaucoup de clients demandent d’avoir la doc sur Confluence, je n’aime pas mais pas le choix.

Par contre, beaucoup de clients demandent d’avoir la doc sur Confluence, je n’aime pas mais pas le choix.

J’ai eu ce cas de figure dans un boulot précédent: je devais écrire une doc dans un wiki Confluence :nauseated_face:. Je l’ai écrit en org-mode (c’est le même principe que markdown), puis exporté en fichier libreoffice et importé dans Confluence en tant que document Word. :innocent:

Super présentation,

J’ai découvert quelques outils intéressant à ajouter à notre stack comme le linter de lien 404.

On utilise en partie les mêmes outils avec quelques extensions en plus. Avez-vous essayé Mermaid à la place de drawIO et PlanUML. Moi j’en suis bien content et je trouve cela plus simple à prendre en main.

Je suis tombé sur Mermaid après avoir mis en place PlantUML.

J’avais déjà été relativement incompris avec ma volonté d’automatiser le modèle de donnée d’un projet alors je n’ai pas pris le temps de tester Mermaid du coup…

Un compagnon aurait peut-être utilisé ces 2 outils pour en faire un retour?

1 J'aime

Concernant la génération de diagrammes, je recommande https://kroki.io/ (développé par un ami, j’ai donné un coup de main pour la CLI) qui supporte quasi tous les formats de diagrammes et permet de facilement les tester, générer, et inclure dans de la doc.

Vous pouvez même passer votre diagramme texte en base64 en paramètre d’URL et kroki vous le générera, vous n’avez besoin de rien en local (voir la page examples).

1 J'aime

J’avais fais une tentative avec Mermaid mais la syntaxe devient très vite indigeste. Du coup, je suis passé à Diagrams : https://diagrams.mingrammer.com/.

Mes retours perso sur

  • DrawIO: nickel quand on veut faire des diagrammes un peu complexe mais sans se soucier de l’aspect “as code”. Si tu changes le sens d’une flêche, ta Pull/Merge Request ne te dira pas exactement ce qu’il change. Alors que Mermaid/PlantUML, oui. Avec DrawIO, on ne maintien qu’un seul fichier (png ou svg), ce qui permet de rendre l’image directement utilisable, et le source est en metadonnées dans le fichier png/svg.
  • Mermaid: facile pour créer des diagrammes. Il y aussi plusieurs extensions VSCode qui permettent d’aller plus vite. Par contre, j’ai vite trouvé les limitations dès qu’il faut créer des diagrammes d’archi (AWS, GCloud, …). Désavantage: il faut forcément avoir la librairie pour visualiser le diagramme (ou un outil qui va générer l’image dynamiquement)
  • PlantUML: une énorme collection de type de diagrammes, avec des librairies toutes faîtes. Même désavantage que Mermaid (il faut savoir faire le rendu de la description en PNG/SVG), sachant qu’il y a quand même le serveur plantUML qui peut le faire (ce qui inclue donc une dépendence sur le service)

Merci à @mcorbin pour kroki.io - ça à l’air assez génial !

2 J'aime

Ouais, merci mcorbin pour kroki, je vais tester ça.

Pour les archis, y a diagrams pour faire du diagram as code.
Il existe le pendant en golang (mais moins fourni de mémoire). Je peux retrouver le lien si ça intéresse.

1 J'aime

L’intégration Kroki est maintenant disponible dans Gitlab (ça vient d’arriver avec la dernière release): https://docs.gitlab.com/ee/administration/integration/kroki.html

3 J'aime

Hello @ojacques,

Merci pour ton partage. J’ai vu dans les slides que tu utilisais markdown-link-check. Je l’utilisais aussi pour vérifier les liens de mon wiki sous gitlab, et comme j’avais quelques modifications à apporter au projet, je l’ai forké, réecrit complétement en typescript et ajouté des fonctionnalités (gestion multi pages, cache, statistique, …). Si vous êtes intéressés par cette version, voici le point de départ : https://www.npmjs.com/package/@boillodmanuel/markdown-link-check (+ le repo github). A votre dispo si vous avez besoins d’info ou de features.

Manuel

2 J'aime

Super, merci @manuel . On va passer sur ta version.