Publish docs on readthedocs

[camillemonchicourt]

No description provided.

[bruhnild]

Changements visibles ici : https://geotrek-rando-v3.readthedocs.io/latest/

[camillemonchicourt]

OK pour moi (hormis le copyright), ça rend bien comme ça.

[camillemonchicourt]

Quelques ajustements.

[camillemonchicourt]

Par contre, j'avais identifié quelques soucis avec mkdocs.
Les code blocks ne peuvent pas être indenté comme mentionné ici : https://www.mkdocs.org/user-guide/writing-your-docs/#fenced-code-blocks

Exemple ici de code bloc indenté :

Non indenté est OK :

La seule bonne solution pour cela semble être l'ajout de l'extension https://facelessuser.github.io/pymdown-extensions/extensions/superfences/, comme discuté ici : mkdocs/mkdocs#282 (comment)

---

Et les notes, warning and co qui ne sont pas interprétés :

Alors que c'est le cas sur Github :

Je ne les ai peut-être pas renseignés comme il faut. Je creuse un peu ça.

---

Après si mkdocs c'est pas idéal, j'ai pas de préférence d'outil.
Mais l'important est que ça soit simple à mettre en place, déployer et maintenir (installer le moins d'outils et d'extensions) pour que ça soit stable dans le temps, simple de contribuer (markdown idéal), et le plus homogène possible entre Geotrek-admin et Geotrek-rando en terme de présentation et d'affichage.

[bruhnild]

J'ai réindenté les bouts de code et l'affichage est beaucoup mieux.

[camillemonchicourt]

J'ai réindenté les bouts de code et l'affichage est beaucoup mieux.

Oui, du coup ce n'est plus forcément bien aligné quand c'est dans une liste ou un sous-ensemble, mais il vaut mieux en effet.

[bruhnild]

Ok pour merger ?

[bruhnild]

Nouveau thème Material for mkdocs ==> https://geotrek-rando-v3.readthedocs.io/latest/

[babastienne]

Quelques sujets / questions :

• Je trouve très bizarre d'un point de vue cohérence qu'il y ai tout en anglais SAUF la page "présentation générale" qui est en français. Pour moi soit on fait une doc complète en anglais soit on traduit tout en français et on laisse aux utilisateurs la possibilité de choisir une langue dans l'interface. C'est déjà un problème qu'on a sur Geotrek-Admin et ca serait chouette de ne pas le reproduire, autant le corriger maintenant sachant qu'il n'y a qu'une seule page à traduire en anglais.
• A minima si on garde cette page telle quelle il faudra alors dans tous les liens qui pointent vers cette page mentionner à côté que c'est en français car sinon ce n'est vraiment pas clair d'un point de vue navigation où on passe sans avertissement d'une langue à une autre.
• Est-ce qu'on est obligés de mettre partout geotrek-rando V3. Y a-t-il encore besoin de distinguer les versions sachant que la v2 n'est plus maintenue et archivée ?
• Avant de merger : la PR a-t-elle été rebased sur la dernière release pour vérifier qu'on a bien toutes les dernières modifications de doc réalisées dans les dernières PR mergée ?

[camillemonchicourt]

• Pour la partie PRESENTATION, en effet, c'est un peu bizarre. Mais en fait celle-ci était clairement destinée aux utilisateurs de la communauté, et non pas aux techniciens, raison pour laquelle je l'ai faite en français car sinon elle aurait perdu un peu sa cible. En fait c'est comme dans la doc de Geotrek-admin où le manuel utilisateur est en français, tandis que tout le reste de la doc est en anglais (car destiné à un public qui est plus familier avec cette langue). N'ayant pas le temps de faire les 2 langues pour tout et de les maintenir/mettre à jour, pour moi le compromis est acceptable. Je ne pense pas qu'on sera en capacité de gérer et mettre à jour toute la doc en 2 langues. En attendant doc utilisateur en FR et doc technique en EN est un compromis acceptable pour moi.
• OK pour moi de parler désormais de Geotrek-rando sans préciser V3

[dtrucs]

Pour le dernier point, aucun apport de doc n'a été fait depuis le fork de cette PR. Juste le changelog qui a conflict avec la release de ce matin

[bruhnild]

J'ai retiré les mentions Rando V3 et précisé (french) lorsqu'une page fait référence à la page de présentation rédigée en français (https://geotrek-rando-v3.readthedocs.io/latest/presentation-fr/).

J'ai voulu mettre en place un mécanisme de changement de langue (anglais/français) mais :

1. Est ce pertinent dans la mesure où il n'existe actuellement qu'un seule page en français dans la documentation ? Il est toujours possible de traduire l'ensemble des pages dans les deux langues mais comme dit Camille, je ne pense pas qu'on aura la capacité de maintenir ce fonctionnement sur la durée.
2. Semble techniquement plus compliqué que prévu (voir https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/)

[babastienne]

@bruhnild pour moi pas besoin d'activer deux langues pour le moment. Si tu mentionné quand on mettais le lien que la page était français c'est suffisant.

Merci pour la mise à jour de la doc. 🙏

Je n'ai pas vérifié (pas assez de réseau pour charger la page de diff), mais il faut aussi en profiter pour mettre à jour le readme du projet et indiquer la lien vers la nouvelle doc.

Pour le reste c'est ok pour moi, on peut merger.

---

Rien à voir, mais est-ce qu'on ne profiterai pas de cette "nouvelle" doc pour en faire la com' auprès de la communauté ? Un mail sur la mailing liste en mode "Heyyy, pour info voici la nouvelle doc GTR3 : . N'hésitez pas à aller la voir et à nous remonter sur ce ticket (insérer lien vers un ticket) si vous trouvez certaines choses manquantes ou peu claires, nous avons besoin de vos retours pour l’améliorer". Idem si vous avez des idées et souhaits de nouvelles fonctionnalités ou si vous identifiez des choses qui vous paraissent manquantes" ? Je me dis que ça pourrait être l'occasion d'obtenir des retours de la communauté car peut-être certaines personnes n'osent pas ou n'y pensent pas le reste du temps ?

[babastienne]

@dtrucs peux-tu regarder le diff et voir si ça te semble ok de ton côté les modifs avant de merger ?

[bruhnild]

Readme mis à jour.

[dtrucs]

@bruhnild
1/ pourquoi avoir déplacé énormément de fichier dans un dossier /fr/ ?
2/ rajouter une custo dans /customization/, je suis ok mais ça ne serait pas mieux de mettre quelque chose qui ressemble à geotrek plutôt que copier celle du département du 62? Je pense qu'il ne faudrait pas mettre de scriptsHeader (ou autre chose que des scripts analytics)

[dtrucs]

@submarcos could you review parts related to python stuff?

[camillemonchicourt]

@bruhnild 1/ pourquoi avoir déplacé énormément de fichier dans un dossier /fr/ ? 2/ rajouter une custo dans /customization/, je suis ok mais ça ne serait pas mieux de mettre quelque chose qui ressemble à geotrek plutôt que copier celle du département du 62? Je pense qu'il ne faudrait pas mettre de scriptsHeader (ou autre chose que des scripts analytics)

• Oui là y a eu un soucis il me semble. Je pense pas que l'intégration de la custo d'un département soit volontaire.
• Et je ne comprends pas non plus tout le contenu duplique dans /fr/. A supprimer il me semble, on ne prévoit pas de maintenir une doc en EN et en FR. Seulement en EN pour tout le volet technique, et en FR pour la présentation générale.

[bruhnild]

Effectivement, il y a eu un commit malheureux qui a embarqué des fichiers indésirables. Le dossier /fr a été supprimé ainsi que les fichiers de customization qui n'avaient rien à y faire.
Le reste semble ok, ne manque plus que la review sur le fichier requirements.txt

[camillemonchicourt]

Le fichier README.md sera aussi celui affiché sur la page d'accueil quand on arrive sur le Github : https://github.com/GeotrekCE/Geotrek-rando-v3
Et selon moi, en l'état il ne colle pas avec cet usage : https://github.com/GeotrekCE/Geotrek-rando-v3/blob/add-readthedocs/README.md

On ne devrait pas inclure ce README dans la documentation, et faire en sorte qu'il contienne le minimum nécessaire quand on arrive sur le Github du projet (image et texte de présentation de base, lien vers la doc...).

[bruhnild]

• Readme mis à jour avec de nouvelles sections (features, license, contribution, contributors, etc.)
• index.md (page d'accueil de la doc) simplifié

[babastienne]

Très chouette cette nouvelle page de readme.

Maintenant j'ai envie de faire la même chose sur GTA 😆

[babastienne]

Suggested change

	Demo available at [https://gtr3demo.ecrins-parcnational.fr](https://gtr3demo.ecrins-parcnational.fr).
	You can find two demonstration website at the following addresses :
	- [https://gtr3demo.ecrins-parcnational.fr](https://gtr3demo.ecrins-parcnational.fr)
	- [https://demo-rando.geotrek.fr/](https://demo-rando.geotrek.fr)
	Discover more users close to your place by going onto the [user map](https://geotrek.fr/utilisateurs.html).

Je me dis que pour les deux instances de démo ça serait chouette aussi de mettre un lien vers l'admin (+ identifiants) pour quel les curieu·x·ses puissent aller tester des modifications ? Mais est-ce l'endroit pour mettre des liens vers l'admin ? Est-ce qu'il ne faudrait pas plutôt mettre un lien vers une section "Démo" équivalente sur le répo de Geotrek-Admin (à créer) ?

[camillemonchicourt]

On pourrait aussi mettre directement 2 ou 3 exemples de vrais portails pour montrer des vrais usages, moins basiques, non ?
Mettre les liens des admins, etc... pourquoi pas, mais faut pas que ça devienne un peu complexe de s'y retrouver dans trop de liens et d'infos. Pas d'avis tranché donc.

[bruhnild]

J'ai créé une section "Examples of Geotrek-rando portals" avec 4 randos + un montage d'images pour illustrer.

[bruhnild]

pour les liens de l'admin je n'ai rien fait pour l'instant, pas trop d'idée sur la façon de les présenter dans le readme.

[babastienne]

@dtrucs go pour merger cette PR ?