Étudier et Benchmark les outils de génération de documentation

[stephane-klein]

Sphinx est peut-être le premier générateur de documentation que j'ai utilisé vers 2008.

Sphinx était (et est toujours) très bien : complet, moteur de recherche, stable, énormément d'utilisateurs dans la communauté Python... Vers 2010, le choix était simple, il n'y avait pas de questions à se poser, étant donné que Sphinx était presque le seul et dominait totalement le "marché".

Depuis la progression spectaculaire de l'écosystème JavaScript, la donne a changé : il existe un large choix et générateurs de documentation. Le choix n'est plus simple.

Je pense que Sphinx est toujours un choix pertinent, mais Sphinx est écrit en Python et Python n'a pas la cote chez les développeurs JavaScript.

D'autre part, les générateurs de documentation, basés sur un moteur JS, permettent pour la plupart d'intégrer des Components riches (ReactJS) dans les pages, ce qui peut-être dans certaines situations très pratiques.

Concernant le dialecte Markdown, AsciiDoc, ReStructuredText, je pense que je préfère être conservateur, c'est à dire utiliser du Markdown afin que la source des pages soit correctement rendu dans GitHub ou GitLab.

Dans mes critères de comparaison, je souhaite étudier :

• la vitesse de build
• la qualité de la navigation :
  • page précédente/ suivante
  • sommaire de la page
  • sections
• qualité de la documentation de l'outil
• moteur de recherche basé sur :
  • basé sur https://lunrjs.com/
  • ou MelliSearch
• Support monorepos, c'est-à-dire, peut être setup comme ceci :

  /docs/... <= les fichiers de documentation (.md) sont placés ici
  /services/document-engine/... <= Docusaurus, docz, Vitepress, Nextra… doivent être installé ici

• Support i18n du type suivant :

  /docs/page1.en.md
  /docs/page1.fr.md
  /docs/page2.en.md
  /docs/page3.fr.md
  /docs/page4.en.md
  /docs/page5.fr.md
  ...

Je ne souhaite plus essayer de configurer le générateur de doc sur la structure de fichiers des README.md d'un monorepo. J'ai perdu trop de temps à faire cela, aucun outil ne le supporte et les hacks que j'ai essayé de mettre en place ont engendré trop de difficultés, problèmes... Par conséquent, la documentation doit rester une documentation, qui suit une narrative, et à côté de cela, des fichiers README.md continuent à exister dans les dossiers des services, outils, environnement... qui fournissent de la documentation contextuelle.

Todo :

• [ ] Faire la liste des générateurs de documentation que j'aimerais tester
  • [ ] https://github.com/mkdocs/mkdocs/ (en Python)
  • [ ] https://github.com/facebook/docusaurus (basé sur ReactJS)
  • [ ] https://www.sphinx-doc.org (en Python)
  • [ ] #23
  • [ ] https://github.com/vuejs/vitepress (basé sur VueJS)
  • [ ] https://github.com/doczjs/docz (basé du GatsbyJS)
  • [ ] https://github.com/markdoc/markdoc (en React, créé par Stripe)
  • [ ] https://github.com/shuding/nextra (basé sur Next.js)
  • [ ] https://vuepress.vuejs.org/ (basé sur VueJS)
  • [ ] https://github.com/rust-lang/mdBook (en Rust)
• [ ] Tester
• [ ] ...

Tableau de comparaison : https://docs.google.com/spreadsheets/d/1xZlg0nabIUTH54xzsJ62D5hpc-plDUA8SDkJWp1bFDE/edit?usp=sharing

Mon cahier des charges

• Support d'un moteur de recherche static du style :
  • https://lunrjs.com/
  • ou https://github.com/jameslittle230/stork (qui semble plus moderne)
• Support de TOC sur des pages markdown
• Support page précédente / suivante
• Support i18n, idéalement cette structure d'organisation de fichiers

  /docs/page1.md
  /docs/page1.fr.md
  ...

• Support du placement des ressources markdown dans un dossier parent
• Idéalement, possibilité d'implémenter des pages en SSR

Playground repositories

• https://github.com/stephane-klein/docusaurus-playground
• https://github.com/stephane-klein/nextra-playground
• https://github.com/stephane-klein/kit-docs-playground

[stephane-klein]

See https://news.ycombinator.com/item?id=31343371

[stephane-klein]

Je lis https://markdoc.io/docs/overview

[stephane-klein]

Je lis https://github.com/facebook/docusaurus/issues/6113

[stephane-klein]

Exemple de sites qui utilisent Docusaurus : https://docusaurus.io/showcase

[stephane-klein]

Je souhaite dans un premier temps tester les plugins de moteur de recherche local suivants (je ne souhaite pas utiliser Algolia) :

• [ ] https://github.com/praveenn77/docusaurus-lunr-search (241 stars)
• [ ] https://github.com/daldridge/docusaurus-plugin-lunr (30 stars)
• [ ] https://github.com/typesense/docusaurus-theme-search-typesense

[stephane-klein]

Je fais mes tests Docusaurus dans le repository suivant : https://github.com/stephane-klein/docusaurus-playground

[stephane-klein]

Dans ce commit, j'ai réussi à setup docusaurus-lunr-search avec succès.

À noter que :

$ pnpm run swizzle docusaurus-lunr-search SearchBar -- --danger

ne fonctionne pas, j'ai dû passer par npm et lancer :

$ npm run swizzle docusaurus-lunr-search SearchBar -- --danger

[stephane-klein]

Je souhaite tester si je peux placer un dossier de /docs/ dans un dossier parent à Docusaurus, exemple :

/docs/...
/services/docusaurus/...
/services/docusaurus/packages.json

[stephane-klein]

Je souhaite tester si je peux placer un dossier de /docs/ dans un dossier parent à Docusaurus

Cela a fonctionné, exemple :

https://github.com/stephane-klein/docusaurus-playground/commit/e796c8b6d96c69196ab6ef18e575c6c3ca92b105

[stephane-klein]

Je souhaite tester la fonctionnalité i18n de Docusaurus.

[stephane-klein]

Je n'ai pas trouvé dans kit-docs de fonctionnalité "i18n" qui ressemble au fonctionnement de Docusaurus, c'est-à-dire ce type de dropdown :

J'ai trouvé cette issue : https://github.com/svelteness/kit-docs/issues/26

[stephane-klein]

Je trouve ce point très pénible dans Docusaurus :slightly_frowning_face:

[stephane-klein]

J'aime bien l'organisation des fichiers pour le support i18n de Nextra : https://nextra.vercel.app/features/i18n

Autre intérêt de Nextra : le support SSG qui permet par exemple d'afficher des données dynamiques qui viennent par exemple d'une base de données.

[stephane-klein]

J'ai trouvé cette issue : https://github.com/svelteness/kit-docs/issues/26

On m'a répondu : https://github.com/svelteness/kit-docs/issues/26#issuecomment-1172873835

[stephane-klein]

En regardant le code source du thème de Nextra : https://github.com/shuding/nextra/tree/core/packages j'ai l'impression que cet outil est plus "minimaliste" et plus facile à customiser que par exemple Docusaurus.

[stephane-klein]

J'ai créé un playground pour Nextra : https://github.com/stephane-klein/nextra-playground

[stephane-klein]

Je viens de voir que https://github.com/svelteness/kit-docs n'est pas basé sur SvelteKit, ici https://github.com/svelteness/kit-docs/issues/44 je demande pourquoi.

[stephane-klein]

Je trouve ce point très pénible dans Docusaurus slightly_frowning_face

Quelqu'un se pose la même question que moi : https://github.com/facebook/docusaurus/issues/7377.

[abordin-spacefill]

@stephane-klein Pour info, une version 2.0 de nextra est sortie il y a quelques jours https://github.com/shuding/nextra/releases/tag/nextra%402.0.0

[stephane-klein]

@abordin-spacefill merci :+1:, très intéressant.

La gestion i18n de Nextra correspond à ce que je cherche : https://nextra.site/docs/guide/i18n#use-add-locale-to-filenames

[stephane-klein]

@abordin-spacefill Je viens de voir que j'avais noté ceci :

J'aime bien l'organisation des fichiers pour le support i18n de Nextra : https://nextra.vercel.app/features/i18n

Je ne me souviens plus pourquoi j'avais arrêté de travailler sur https://github.com/stephane-klein/nextra-playground

[stephane-klein]

Je ne me souviens plus pourquoi j'avais arrêté de travailler sur https://github.com/stephane-klein/nextra-playground

@abordin-spacefill je pense que c'était à cause de difficulté en mode mono repos, voire cette branche https://github.com/stephane-klein/nextra-playground/commits/monorepo

[stephane-klein]

Un autre moteur de recherche static https://github.com/nextapps-de/flexsearch

[stephane-klein]

La section benchmark de ce repos liste de nombreux moteur de recherches static.

[stephane-klein]

https://vercel.com/templates?utm_source=next-site&utm_medium=navbar&utm_campaign=home&framework=next.js&type=documentation

[stephane-klein]

https://www.writethedocs.org/guide/docs-as-code/

[stephane-klein]

https://github.com/jean-humann/docs-to-pdf

[stephane-klein]

https://github.com/sydasif/my-pandoc-book

[stephane-klein]

Je suis en train de créer un spike privé basé sur Docusaurus, pour le moment, ce que je trouve pénible :

• par défaut, Docusaurus propose trop de fonctionnalités pour moi : blog, home page…
• je trouve Docusaurus lent à build