📝 [Documentation] Reorganize sections in doc

[bruhnild]

Description

Related Issue

Checklist

• I have followed the guidelines in our Contributing document
• My code respects the Definition of done available in the Development section of the documentation
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes
• I added an entry in the changelog file
• My commits are all using prefix convention (emoji + tag name) and references associated issues
• I added a label to the PR corresponding to the perimeter of my contribution
• The title of my PR mentionned the issue associated

[bruhnild]

• Issue liée : Réorganisation de la doc #4415
• Lien de la doc pour tester : https://geotrek.readthedocs.io/en/mfu-improve-doc-gta/

[camillemonchicourt]

C'est bien d'avoir regroupé tout ce qui concerne l'import.
Mais par contre, on comprend moins ce qui est lié à l'import initial des données minimales pour avoir un Geotrek fonctionnel dans la foulée de son installation. Et ce qui concerne l'import de données complémentaires ou en continu, au fil du projet.
A voir comment préciser/clarifier ça.
J'essaie de relire plus en détail dès que possible.

[babastienne]

on comprend moins ce qui est lié à l'import initial des données minimales pour avoir un Geotrek fonctionnel dans la foulée de son installation

Peut-être ajouter à la fin de la page d'installation une mention "Une fois votre Geotrek installer, il faut importer des données initiales" (avec un lien vers la page dédiée)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.46%. Comparing base (fe60cf0) to head (ac40636).
Report is 7 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #4424   +/-   ##
=======================================
  Coverage   98.46%   98.46%           
=======================================
  Files         268      268           
  Lines       21290    21290           
=======================================
  Hits        20964    20964           
  Misses        326      326           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[cypress]

Geotrek-admin    Run #10661

Run Properties:   Passed #10661  •  cf0ac08747 ℹ️: Merge ac40636268ba8b5745bb901e47fc4fe8a7d10702 into 17cd74274512b55aa3bf46a7b05a...

Project	Geotrek-admin
Branch Review	refs/pull/4424/merge
Run status	Passed #10661
Run duration	02m 11s
Commit	cf0ac08747 ℹ️: Merge ac40636268ba8b5745bb901e47fc4fe8a7d10702 into 17cd74274512b55aa3bf46a7b05a...
Committer	Marine Faucher
View all properties for this run ↗︎

---

Test results
Failures	0
Flaky	0
Pending	0
Skipped	0
Passing	22
View all changes introduced in this branch ↗︎

[babastienne]

Sur certaines pages il y a des titres de section qui sont "bizarres"

C'est déjà le cas aujourd'hui mais ça pourrait être corrigé au passage

[camillemonchicourt]

Pour moi, ces données sont les données initiales minimales (Minimal initial data), donc à préciser dans le titre ou dans un petit texte, surtout maintenant que c'est déplacé plus bas dans la documentation.

[bruhnild]

C'est fait, il y a désormais un message en base de la page Installation qui renvoie vers la page Prerequisites for your data sur laquelle on trouve aussi un message qui précise que les données listées sont celles des données initiales.

[camillemonchicourt]

OK, mais en fait je crois que je comprends pas ce titre de rubrique.
"Importer des données / Pré-requis pour vos données".
En fait le titre devrait uniquement être "Minimal initial data" plutôt, non ?

[bruhnild]

Oui, je reconnais que le titre pouvait porter à confusion, je l'ai changé : https://geotrek.readthedocs.io/en/mfu-improve-doc-gta/install/minimal-initial-data.html

[bruhnild]

Sur certaines pages il y a des titres de section qui sont "bizarres"

C'est déjà le cas aujourd'hui mais ça pourrait être corrigé au passage

Oui, il s'agit de la syntaxe .. envvar:: qui est mal interprétée dans le thème de la doc. Il y en avait énormément dans la page advanced configuration.
Je les ai tous remplacé par des titres de 4 ème ou 3èeme niveau.

[camillemonchicourt]

OK globalement pour moi.
Sauf les histoires d'URL des pages et sections qui vont pas mal changer, et sans redirection ça va poser soucis.

• Si je tombe sur une ancienne version d'une page comme https://geotrek.readthedocs.io/en/2.90.0/install/loading-data.html depuis un lien externe, je clique sur "This may be an old version of this documentation
  You may be reading an old version of this documentation. Read the latest stable version of this documentation." J'ai tomberai alors sur une erreur 404.
• Si je tombe sur une URL externe vers une section de la documentation en mode "master", "latest" ou "stable" (que je privilégie pour rester à jour quand je partage une URL de doc), comme https://geotrek.readthedocs.io/en/stable/install/loading-data.html, alors je tomberai sur une Erreur 404 aussi.

[babastienne]

Si je tombe sur une URL externe vers une section de la documentation en mode "master", "latest" ou "stable" (que je privilégie pour rester à jour quand je partage une URL de doc)

Pour moi ça c'est une mauvaise pratique qu ne doit pas être réalisée.

---

Pour les redirections je suis pour en mettre en place uniquement pour les pages qui sont régulièrement partagées (pourquoi pas la page cirkwi par exemple). Mais sinon si on doit le faire pour toutes les pages tout le temps à chaque fois que la doc est modifiée c'est pas tenable comme système.

Une documentation ça vie, ça évolue, c'est normal que les pages ne soient pas toujours les mêmes.

Et d'ailleurs en creusant je vois que Cirkwi a su adapter leur lien vers la documentation quand il fallait puisque la page actuelle utilise une URL qui n'était pas celle-ci auparavant et sur laquelle il n'y avait pas de redirection d'effectué.

[babastienne]

Bon sinon, j'en peux plus de cette page infernale : https://geotrek.readthedocs.io/en/mfu-improve-doc-gta/install/advanced-configuration.html

Est ce qu'on en ferait pas une section à part, au même titre qu'on en a fait une pour Import data ?

Oui on pourrait faire ça. Ca ferait donc trois grosses sections :

• Installation (+ maintenance, upgrade, etc)
• Configuration
• Import data

Si on sépare cette grosse page de settings en plusieurs il faudrait trouver une organisation "logique" quand même. Car aujourd'hui l'avantage d'une seule page c'est que quand on cherche un paramètre on sait qu'on va le retrouver dedans. Si c'est sur plusieurs pages ça implique de chercher un peu plus donc il faut que ce soit clair ce qui est sur chaque page.

(bon ceci dit la fonction de recherche de la doc marche très bien)

[bruhnild]

Bon sinon, j'en peux plus de cette page infernale : https://geotrek.readthedocs.io/en/mfu-improve-doc-gta/install/advanced-configuration.html
Est ce qu'on en ferait pas une section à part, au même titre qu'on en a fait une pour Import data ?

Oui on pourrait faire ça. Ca ferait donc trois grosses sections :

* Installation (+ maintenance, upgrade, etc)

* Configuration

* Import data

Si on sépare cette grosse page de settings en plusieurs il faudrait trouver une organisation "logique" quand même. Car aujourd'hui l'avantage d'une seule page c'est que quand on cherche un paramètre on sait qu'on va le retrouver dedans. Si c'est sur plusieurs pages ça implique de chercher un peu plus donc il faut que ce soit clair ce qui est sur chaque page.

(bon ceci dit la fonction de recherche de la doc marche très bien)

J'ai un peu pris les devants depuis mon commentaire et splité la page en autant de sous-pages qu'il y avait de sous-titres pour garder la structure. L'organisation reste la même mais on y voit plus clair pour réorganiser en profondeur : https://geotrek.readthedocs.io/en/mfu-improve-doc-gta/advanced-configuration/application-settings.html

[babastienne]

Est-ce bien utile de conserver en haut de chaque page un bloc "table of content" (1) alors qu'il y en a déjà une à droite de la page (2) ?

Pour alléger j'aurai tendance à retirer ça sur l'ensemble des pages.

[bruhnild]

Est-ce bien utile de conserver en haut de chaque page un bloc "table of content" (1) alors qu'il y en a déjà une à droite de la page (2) ?

Pour alléger j'aurai tendance à retirer ça sur l'ensemble des pages.

Effectivement, c'était redondant et alourdissait les pages. J'ai retiré les TOC sur toutes les pages de la doc (le menu de droite s'en charge)