different version of the site

[jeanmi151]

https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/

[MaelREBOUX]

RTD : beurk

[gryckelynck]

J'ai fait un test rapide avec https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/
et https://github.com/jimporter/mike

Rien de bien compliqué : installer et utiliser "mike serve" pour le développement et "mike deploy"
J'ai juste ajouté une propriété dans le fichier YAML: https://gitea.datagrandest.net/guillaume_ryckelynck/georchestra_documentation_module_test/src/branch/master/mkdocs.yml#L23
Le plus gros impact est sur l'organisation du dépôt puisque le déploiement se fait visiblement directement dans le dépôt distant dans une branche dédiée "gh-pages" (cela ne me semble pas configurable).

Voilà ce que j'obtiens :

• côté dépôt: https://gitea.datagrandest.net/guillaume_ryckelynck/georchestra_documentation_module_test/src/branch/gh-pages
• côté site: https://www.datagrandest.fr/tmp/georchestra_documentation_module_test_versions/0.2/

NB: je n'ai par contre par regardé le "version warning" (cf. https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/#version-warning)

[jeanmi151]

le résultat est vraiment sympa ;)
par contre j'ai pas trop compris comment sa "crée" une version

[gryckelynck]

par contre j'ai pas trop compris comment sa "crée" une version

Après installation de "mike", il faut l'utiliser pour le déploiement de la documentation.
Il va automatiquement créer une branche "gh-pages" dans le dépôt git et gérer l'arborescence adaptée en fonction des version publiées.
Dans https://gitea.datagrandest.net/guillaume_ryckelynck/georchestra_documentation_module_test/src/branch/gh-pages on voit les dossiers "0.1" et "0.2" qui correspondent aux 2 versions de test que j'ai déployé.
Si je fais des modifs dans la documentation et lance "mike deploy 0.3" il va me créer une version 0.3 donc un dossier 0.3 dans la branche gh-pages de git. On peut aussi utiliser des alias de type "mike deploy 0.3 latest", mais le test que j'ai fait n'a pas été concluant et je n'ai pas creusé.

[jeanmi151]

okay, je ne suis pas sûr que cela soit adapté le but est de ne pas utiliser github pages mais plutôt readthedocs.io (à voir avec @MaelREBOUX )

[jeanmi151]

Si c'est compatible il faudra pas oublier de mettre à jour le README et les lib requise (requirements.txt)

[MaelREBOUX]

OK. Le résultat visible par le lecteur est super propre et intéressant.

Ce qui m'interroge à chaud c'est la création obligée d'un branche gh-pages dans le dépôt logiciel pour accueillir la compilation d'une version de la documentation (gênant / pas gênant ?)

De ce que j'ai compris @gryckelynck a posé la doc compilée (ou un git clone du repo sur la branche 'gh-pages') sur un serveur web (https://www.datagrandest.fr/tmp/georchestra_documentation_module_test_versions/).
Donc pas forcément de dépendances à github pages mais par contre ça nous demanderait à gérer la doc sur notre serveur "docs" de geOrchestra alors que l'idée était de se simplifier la vie et de données des accès aux mainteneurs des documentations sur RTD (plus clic-bouton).
Comme ils le disent dans la doc si on veut que ça publie de la doc compilée il faut mettre en place une CI. Ce qu'on veut éviter en premier abord.

Pas simple tout ça.

[gryckelynck]

Donc pas forcément de dépendances à github pages mais par contre ça nous demanderait à gérer la doc sur notre serveur "docs" de geOrchestra

Je confirme : j'ai généré la doc versionnée en local avec mike (dans une branche locale gh-pages) et j'ai poussé le résultat sur un serveur web. Je ne pense pas que centraliser tout sur le serveur "docs" de geOrchestra soit nécessaire.
Une alternative, serait de demander à chaque gestionnaire de documentation de pousser sa doc HTML sur son dépôt GitHub (de préférence via mike) et de faire pointer RTD sur la branche "gh-pages" ainsi générée. A voir en // si on désactive la documentation "mondepot.gitub.io" ou si on se permet un double déploiement...
@MaelREBOUX sais-tu si c'est possible de déployer automatiquement un site static HTML sur RTD à partir d'une branche GitHub ?

A noter aussi que j'ai trouvé cela qui peut être intéressant, même si je ne connais pas suffisamment RTD pour tout comprendre : squidfunk/mkdocs-material#3566

[gryckelynck]

En complément, si ça peut aider à comprendre, un retour d'expérience sur le déploiement de la doc sur GitHub Pages via mkdocs/mike:

• Je gère ma doc (mkdocs) ici : https://github.com/datagrandest/dge-dataviz-components/tree/main/documentation
• Je déploie via mike (branche gh-pages) ici : https://github.com/datagrandest/dge-dataviz-components/tree/gh-pages
• J'ai mon résultat (mis à jour par GitHub à chaque publication) ici : https://datagrandest.github.io/dge-dataviz-components/4.5.1/index.html