Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
13 tasks
stephane-klein opened this issue Jun 20, 2022 · 29 comments
Open
13 tasks

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

stephane-klein opened this issue Jun 20, 2022 · 29 comments
Labels
learn-in-public

Comments

@stephane-klein
Copy link
Owner

stephane-klein commented Jun 20, 2022 •
edited
Loading

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 :
  • 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 :

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 :
  • 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
@stephane-klein
Copy link
Owner Author

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

@stephane-klein
Copy link
Owner Author

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

@stephane-klein
Copy link
Owner Author

Je lis facebook/docusaurus#6113

@stephane-klein
Copy link
Owner Author

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

@stephane-klein
Copy link
Owner Author

stephane-klein commented Jul 1, 2022 •
edited
Loading

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

@stephane-klein
Copy link
Owner Author

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

@stephane-klein
Copy link
Owner Author

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
Copy link
Owner Author

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
Copy link
Owner Author

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

Cela a fonctionné, exemple :

stephane-klein/docusaurus-playground@e796c8b

@stephane-klein
Copy link
Owner Author

Je souhaite tester la fonctionnalité i18n de Docusaurus.

@stephane-klein
Copy link
Owner Author

stephane-klein commented Jul 2, 2022 •
edited
Loading

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
Copy link
Owner Author

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

@stephane-klein
Copy link
Owner Author

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
Copy link
Owner Author

stephane-klein commented Jul 2, 2022 •
edited
Loading

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
Copy link
Owner Author

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
Copy link
Owner Author

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

@stephane-klein
Copy link
Owner Author

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
Copy link
Owner Author

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.

@stephane-klein stephane-klein mentioned this issue Aug 12, 2022
Open
@abordin-spacefill
Copy link

@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
Copy link
Owner Author

@abordin-spacefill merci 👍, 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
Copy link
Owner Author

@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
Copy link
Owner Author

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
Copy link
Owner Author

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

@stephane-klein
Copy link
Owner Author

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

@stephane-klein
Copy link
Owner Author

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

@stephane-klein
Copy link
Owner Author

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

@stephane-klein
Copy link
Owner Author

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

@stephane-klein
Copy link
Owner Author

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

@stephane-klein
Copy link
Owner Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
learn-in-public
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@stephane-klein @abordin-spacefill