Ajouter / améliorer la documentation fonctionelle et technique

[submarcos]

Réflexion autour de la documentation :

• Quel outil / techno utiliser ?
• Quelle mise en place technique / architecture (build automatique sur la CI) ?
• Quelle organisation des contenus (plan) ?

Deux outils identifiés :

• Vitepress
  • fonctionne avec readthedocs
  • gère les versions correspondant à chaque release
  • dépendance à vue dans un ecosysteme reactjs
• Docusaurus
  • basé sur du react js et pas du vue js
  • fonctionnalités à peu près identiques à vitepress
  • stencil doc utilise docusaurus

Actions @bastyen

• [x] Faire une structure minimale de doc sur VitePress et sur Docusaurus (avec plan et exemple intéractif)
• [x] Etudier si on peut switcher facilement ou non de l'un à l'autre
• [x] Voir comment sont gérées les traductions

Action @bruhnild

• [x] Faire le plan de la doc :

• About

  • Geotrek-widget
  • Technos utilisées

• Configuration et installation

  • Paramétrage storybook
  • Description de chaque composant
  • Cas d'usage intégration site internet
  • Exemples d'utilisations

• Manuel utilisateur

  • Composant cartographique
  • Vue liste
    • Design
    • Filtre et recherche
  • Vue détail
  • Gestion contenus touristiques
  • Gestion évènements touristiques
  • Gestion des langues
  • Mode responsive
  • Autres fonctionnalités

• Contribute

Actions @submarcos

• [ ] Déterminer si peut on déployer docausaurus sur readthedocs ?
• [ ] Une fois la solution retenue, regarder comment mettre en place le build/déploiement de la doc sur la CI
• [ ] Voir si on peut utiliser Deepl pour générer du contenu en anglais et l'exécuter dans la CI

[bruhnild]

Retours de @bastyen

Vitepress :

• Simple d'utilisation
• Aucune connaissance de vue nécessaire (exemple configuration widget)
• Facile à mettre en place l'internationalisation (un dossier par langue)
• Définition de l'organisation des sections (plan) dans un fichier de config
• Personnalisation facile de la homepage (markdown) et prête à l'emploi
• Installation très légère et rapide
• Bénéficier des connaissances des nantais (pour la CI par exemple)

Docusaurus:

• Internationalisation un peu plus complexe à mettre en place et surtout, en développement, on peut pas passer d'une langue à l'autre et il faut exécuter une commande spécifique de démarrage du serveur de développement en précisant la langue qu'on veut tester
• Intégration facile du widget mais il faut utiliser des fichiers mdx
• Beaucoup plus de fichiers que sur vitepress
• Demande des connaissances en react (page d'accueil) et montée en compétence
• La partie configuration n'est pas intuitive (docs)
• Initialisation du projet un peu moins rapide que Vitepress

[babastienne]

Haha, j'ai l'impression que les retours sont un peu biaisés :laughing:

Ok merci pour cette analyse @bastyen, je pense que vu les résultats on ne peut pas faire autre chose que de partir sur vitepress :wink:

[camillemonchicourt]

Et pourquoi utiliser un outil si complexe ? Des fichiers markdown avec readthedocs qui tape dessus c'est pas très bien ?

[bastyen]

Justement, on a seulement besoin de fichier markdown avec vitepress et il offre des fonctionnalités supplémentaires comme la possibilité d'y ajouter des composants web, nécessaire pour ce projet afin d'y intégrer des exemples.

On publiera cette documentation sur readthedocs, à terme.

[bastyen]

https://geotrek-rando-widget.readthedocs.io/