docs: add file tree & § about compilationn-peugnet-meta-doc-details

4 files changed, 224 insertions, 60 deletions

diff --git a/README.md b/README.md
index cb0512e..970d58f 100644
--- a/README.md
+++ b/README.md
@@ -8,11 +8,44 @@ La documentation de CLUB1 est publiée au format HTML à l'adresse <https://club
 Elle existe en deux langues : français, la principale et anglais, la secondaire.
 Le site web est généré à l'aide de
 [Sphinx](https://fr.wikipedia.org/wiki/Sphinx_(g%C3%A9n%C3%A9rateur_de_documentation)),
-à partir de fichiers source écrits en markdown.
+à partir de fichiers source écrits en [markdown](https://fr.wikipedia.org/wiki/Markdown).
 Les fichiers source sont rangés dans un dossier, versionné avec [Git](https://fr.wikipedia.org/wiki/Git)
 et accessible publiquement via [GitHub](https://fr.wikipedia.org/wiki/GitHub)
 à l'adresse <https://github.com/club-1/docs/>.
 
+Arborescence du dossier
+-----------------------
+
+L'arborescence ci-dessous présente un résumé de l'arborescence réelle du dossier
+de la documentation de CLUB1.
+
+    ./
+    ├── _build/
+    ├── _static/
+    ├── _templates/
+    ├── locales/
+    │   ├── en/
+    │   │   └── LC_MESSAGES/
+    │   │       └── package.po
+    │   └── package.pot
+    ├── ***/
+    │   └── ***.md
+    ├── AUTHORS
+    └── index.md
+
+- `_build/` : dossier contenant l'ensemble des fichiers générés par Sphinx.
+- `_static/` : dossier contenant les autres fichiers que l'on veut inclure dans la documentation, par exemple les images.
+- `_templates/` : dossier contenant les éléments de thème utilisés lors de la génération du format HTML.
+- `locales/` : dossier contenant les fichiers de traductions.
+  Il comporte un dossier par langue avec des fichiers `.po` contenant les
+  traductions et des fichiers `.pot` générés automatiquement à partir des
+  fichiers source en markdown.
+- `AUTHORS` : fichier contenant la liste des auteurs.
+- `index.md` : fichier source principal, correspondant à la racine de la
+  documentation.
+
+Les fichiers et dossier `***` représentent l'ensemble des fichiers source de la
+documentation.
 
 Proposer des modifications
 --------------------------
@@ -61,6 +94,13 @@ Références
 Compilation
 -----------
 
+Il n'est pas nécessaire de connaître cette section pour participer à l'édition
+de la documentation de CLUB1.
+Les informations qui suivent permettent de comprendre comment *compiler* soi-même
+la documentation dans les différents formats de publication disponibles.
+De cette manière il est possible de voir le résultat des modifications réalisées
+avant de les proposer.
+
 ### Prérequis
 
 | Logiciel         | Détails                                          |
diff --git a/locales/en/LC_MESSAGES/package.po b/locales/en/LC_MESSAGES/package.po
index b7778a2..ad1a098 100644
--- a/locales/en/LC_MESSAGES/package.po
+++ b/locales/en/LC_MESSAGES/package.po
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Hébergement CLUB1 main\n"
 "Report-Msgid-Bugs-To: nicolas@club1.fr\n"
-"POT-Creation-Date: 2022-03-30 14:29+0200\n"
+"POT-Creation-Date: 2022-03-30 15:29+0200\n"
 "PO-Revision-Date: 2022-03-29 21:01+0000\n"
 "Last-Translator: Nicolas Peugnet <n.peugnet@free.fr>\n"
 "Language-Team: English <https://hosted.weblate.org/projects/club-1/docs/en/"
@@ -34,7 +34,7 @@ msgstr ""
 msgid "build"
 msgstr "build"
 
-#: ../../README.md:4 ../../README.md:46
+#: ../../README.md:4 ../../README.md:79
 msgid "Translation status"
 msgstr "Translation status"
 
@@ -44,18 +44,70 @@ msgid ""
 "club1.fr/docs/fr/>. Elle existe en deux langues : français, la principale et "
 "anglais, la secondaire. Le site web est généré à l'aide de [Sphinx](https://"
 "fr.wikipedia.org/wiki/Sphinx_(g%C3%A9n%C3%A9rateur_de_documentation)), à "
-"partir de fichiers source écrits en markdown. Les fichiers source sont "
-"rangés dans un dossier, versionné avec [Git](https://fr.wikipedia.org/wiki/"
-"Git) et accessible publiquement via [GitHub](https://fr.wikipedia.org/wiki/"
-"GitHub) à l'adresse <https://github.com/club-1/docs/>."
+"partir de fichiers source écrits en [markdown](https://fr.wikipedia.org/wiki/"
+"Markdown). Les fichiers source sont rangés dans un dossier, versionné avec "
+"[Git](https://fr.wikipedia.org/wiki/Git) et accessible publiquement via "
+"[GitHub](https://fr.wikipedia.org/wiki/GitHub) à l'adresse <https://github."
+"com/club-1/docs/>."
 msgstr ""
 
-#: ../../README.md:17
+#: ../../README.md:16
+msgid "Arborescence du dossier"
+msgstr ""
+
+#: ../../README.md:19
+msgid ""
+"L'arborescence ci-dessous présente un résumé de l'arborescence réelle du "
+"dossier de la documentation de CLUB1."
+msgstr ""
+
+#: ../../README.md:36
+msgid ""
+"`_build/` : dossier contenant l'ensemble des fichiers générés par Sphinx."
+msgstr ""
+
+#: ../../README.md:37
+msgid ""
+"`_static/` : dossier contenant les autres fichiers que l'on veut inclure "
+"dans la documentation, par exemple les images."
+msgstr ""
+
+#: ../../README.md:38
+msgid ""
+"`_templates/` : dossier contenant les éléments de thème utilisés lors de la "
+"génération du format HTML."
+msgstr ""
+
+#: ../../README.md:39
+msgid ""
+"`locales/` : dossier contenant les fichiers de traductions. Il comporte un "
+"dossier par langue avec des fichiers `.po` contenant les traductions et des "
+"fichiers `.pot` générés automatiquement à partir des fichiers source en "
+"markdown."
+msgstr ""
+
+#: ../../README.md:43
+msgid "`AUTHORS` : fichier contenant la liste des auteurs."
+msgstr ""
+
+#: ../../README.md:44
+msgid ""
+"`index.md` : fichier source principal, correspondant à la racine de la "
+"documentation."
+msgstr ""
+
+#: ../../README.md:47
+msgid ""
+"Les fichiers et dossier `***` représentent l'ensemble des fichiers source de "
+"la documentation."
+msgstr ""
+
+#: ../../README.md:50
 #, fuzzy
 msgid "Proposer des modifications"
 msgstr "Submitting changes"
 
-#: ../../README.md:20
+#: ../../README.md:53
 msgid ""
 "L'utilisation de Git permet à n'importe qui de proposer des modifications. "
 "Pour cela il est possible de modifier les fichiers directement sur GitHub "
@@ -66,17 +118,17 @@ msgid ""
 "principale."
 msgstr ""
 
-#: ../../README.md:28
+#: ../../README.md:61
 msgid ""
 "À chaque mise-à-jour de la branche principale, la documentation est "
 "automatiquement compilée et publiée sur le site web de CLUB1."
 msgstr ""
 
-#: ../../README.md:31
+#: ../../README.md:64
 msgid "Langue française"
 msgstr "French language"
 
-#: ../../README.md:33
+#: ../../README.md:66
 msgid ""
 "Pour modifier une page existante, il faut éditer le fichier `.md` "
 "correspondant. Depuis une page de la doc, un lien pour éditer le fichier sur "
@@ -86,7 +138,7 @@ msgstr ""
 "of the doc, there is a link to edit the page on github in the top-right "
 "corner."
 
-#: ../../README.md:37
+#: ../../README.md:70
 msgid ""
 "Ajoutez une ligne avec votre nom dans le [fichier `AUTHORS`](https://github."
 "com/club-1/docs/edit/main/AUTHORS) après avoir contribué pour la première "
@@ -96,11 +148,11 @@ msgstr ""
 "docs/edit/main/AUTHORS) after having made your first contribution in the "
 "french documentation."
 
-#: ../../README.md:40
+#: ../../README.md:73
 msgid "Autres langues"
 msgstr "Other languages"
 
-#: ../../README.md:42
+#: ../../README.md:75
 msgid ""
 "Les traductions, elles, ne sont pas stockées dans des fichiers markdown, "
 "mais dans des fichiers de locales `locales/*/LC_MESSAGES/package.po` et sont "
@@ -111,7 +163,7 @@ msgstr ""
 "LC_MESSAGES/package.po` files and are more comfortably edited on [Weblate]"
 "(https://hosted.weblate.org/projects/club-1/docs/)."
 
-#: ../../README.md:46
+#: ../../README.md:79
 msgid ""
 "![Translation status](https://hosted.weblate.org/widgets/club-1/-/docs/multi-"
 "auto.svg)"
@@ -119,22 +171,22 @@ msgstr ""
 "![Translation status](https://hosted.weblate.org/widgets/club-1/-/docs/multi-"
 "auto.svg)"
 
-#: ../../README.md:48
+#: ../../README.md:81
 msgid "Ajouter une page"
 msgstr "Add a page"
 
-#: ../../README.md:50
+#: ../../README.md:83
 msgid ""
 "L'ajout de pages ne peut se faire qu'en français. Il faut ajouter un fichier "
 "`.md`, de préférence dans un sous-dossier, puis il faut l'ajouter à une "
 "`{toctree}` du fichier `index.html` (s'inpirer de l'existant)."
 msgstr ""
 
-#: ../../README.md:54
+#: ../../README.md:87
 msgid "Références"
 msgstr "References"
 
-#: ../../README.md:57
+#: ../../README.md:90
 msgid ""
 "[Fonctionnalités Markdown spécifique à MyST-Parser](https://myst-parser."
 "readthedocs.io/en/latest/syntax/syntax.html)"
@@ -142,7 +194,7 @@ msgstr ""
 "[MyST-Parser specific markdown features ](https://myst-parser.readthedocs.io/"
 "en/latest/syntax/syntax.html)"
 
-#: ../../README.md:58
+#: ../../README.md:91
 msgid ""
 "[Spécificités des liens avec Sphinx](https://docs.readthedocs.io/en/stable/"
 "guides/cross-referencing-with-sphinx.html)"
@@ -150,7 +202,7 @@ msgstr ""
 "[Sphinx links specificities](https://docs.readthedocs.io/en/stable/guides/"
 "cross-referencing-with-sphinx.html)"
 
-#: ../../README.md:59
+#: ../../README.md:92
 msgid ""
 "[Tutoriel de configuration de Sphinx avec le thème ReadTheDocs](https://tech."
 "michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/)"
@@ -158,11 +210,21 @@ msgstr ""
 "[Sphinx with ReadTheDocs theme configuration tutorial](https://tech."
 "michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/)"
 
-#: ../../README.md:61
+#: ../../README.md:94
 msgid "Compilation"
 msgstr "Compilation"
 
-#: ../../README.md:64
+#: ../../README.md:97
+msgid ""
+"Il n'est pas nécessaire de connaître cette section pour participer à "
+"l'édition de la documentation de CLUB1. Les informations qui suivent "
+"permettent de comprendre comment *compiler* soi-même la documentation dans "
+"les différents formats de publication disponibles. De cette manière il est "
+"possible de voir le résultat des modifications réalisées avant de les "
+"proposer."
+msgstr ""
+
+#: ../../README.md:104
 msgid "Prérequis"
 msgstr "Prerequisites"
 
@@ -222,27 +284,27 @@ msgstr "imagemagick"
 msgid "(Optionnel) Conversion des SVG pour le PDF LaTeX"
 msgstr "(Optional) SVG conversion for LaTeX PDF"
 
-#: ../../README.md:75
+#: ../../README.md:115
 msgid "Linux basé sur Debian"
 msgstr "Linux based on Debian"
 
-#: ../../README.md:80
+#: ../../README.md:120
 msgid "Commandes"
 msgstr "Commands"
 
-#: ../../README.md:82
+#: ../../README.md:122
 msgid "Compilation en un site statique dans `_build/html`&nbsp;:"
 msgstr "Compilation into a static site in `_build/html`:"
 
-#: ../../README.md:86
+#: ../../README.md:126
 msgid "Compilation d'une locale spécifique&nbsp;:"
 msgstr "Compilation of a specific locale:"
 
-#: ../../README.md:90
+#: ../../README.md:130
 msgid "Mise-à-jour des locales après l'édition des sources&nbsp;:"
 msgstr "Locales update after sources edition:"
 
-#: ../../README.md:94
+#: ../../README.md:134
 msgid ""
 "Toujours vérifier l'état des fichiers `.po` dans `locales` après avoir lancé "
 "l'une de ces commande. Certain passages peuvent ne pas être reconnus si ils "
diff --git a/locales/package.pot b/locales/package.pot
index 41179df..2a36826 100644
--- a/locales/package.pot
+++ b/locales/package.pot
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: CLUB1 main\n"
 "Report-Msgid-Bugs-To: nicolas@club1.fr\n"
-"POT-Creation-Date: 2022-03-30 14:29+0200\n"
+"POT-Creation-Date: 2022-03-30 15:29+0200\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -30,7 +30,7 @@ msgstr ""
 msgid "build"
 msgstr ""
 
-#: ../../README.md:4 ../../README.md:46
+#: ../../README.md:4 ../../README.md:79
 msgid "Translation status"
 msgstr ""
 
@@ -40,17 +40,69 @@ msgid ""
 "club1.fr/docs/fr/>. Elle existe en deux langues : français, la principale et "
 "anglais, la secondaire. Le site web est généré à l'aide de [Sphinx](https://"
 "fr.wikipedia.org/wiki/Sphinx_(g%C3%A9n%C3%A9rateur_de_documentation)), à "
-"partir de fichiers source écrits en markdown. Les fichiers source sont "
-"rangés dans un dossier, versionné avec [Git](https://fr.wikipedia.org/wiki/"
-"Git) et accessible publiquement via [GitHub](https://fr.wikipedia.org/wiki/"
-"GitHub) à l'adresse <https://github.com/club-1/docs/>."
+"partir de fichiers source écrits en [markdown](https://fr.wikipedia.org/wiki/"
+"Markdown). Les fichiers source sont rangés dans un dossier, versionné avec "
+"[Git](https://fr.wikipedia.org/wiki/Git) et accessible publiquement via "
+"[GitHub](https://fr.wikipedia.org/wiki/GitHub) à l'adresse <https://github."
+"com/club-1/docs/>."
 msgstr ""
 
-#: ../../README.md:17
+#: ../../README.md:16
+msgid "Arborescence du dossier"
+msgstr ""
+
+#: ../../README.md:19
+msgid ""
+"L'arborescence ci-dessous présente un résumé de l'arborescence réelle du "
+"dossier de la documentation de CLUB1."
+msgstr ""
+
+#: ../../README.md:36
+msgid ""
+"`_build/` : dossier contenant l'ensemble des fichiers générés par Sphinx."
+msgstr ""
+
+#: ../../README.md:37
+msgid ""
+"`_static/` : dossier contenant les autres fichiers que l'on veut inclure "
+"dans la documentation, par exemple les images."
+msgstr ""
+
+#: ../../README.md:38
+msgid ""
+"`_templates/` : dossier contenant les éléments de thème utilisés lors de la "
+"génération du format HTML."
+msgstr ""
+
+#: ../../README.md:39
+msgid ""
+"`locales/` : dossier contenant les fichiers de traductions. Il comporte un "
+"dossier par langue avec des fichiers `.po` contenant les traductions et des "
+"fichiers `.pot` générés automatiquement à partir des fichiers source en "
+"markdown."
+msgstr ""
+
+#: ../../README.md:43
+msgid "`AUTHORS` : fichier contenant la liste des auteurs."
+msgstr ""
+
+#: ../../README.md:44
+msgid ""
+"`index.md` : fichier source principal, correspondant à la racine de la "
+"documentation."
+msgstr ""
+
+#: ../../README.md:47
+msgid ""
+"Les fichiers et dossier `***` représentent l'ensemble des fichiers source de "
+"la documentation."
+msgstr ""
+
+#: ../../README.md:50
 msgid "Proposer des modifications"
 msgstr ""
 
-#: ../../README.md:20
+#: ../../README.md:53
 msgid ""
 "L'utilisation de Git permet à n'importe qui de proposer des modifications. "
 "Pour cela il est possible de modifier les fichiers directement sur GitHub "
@@ -61,35 +113,35 @@ msgid ""
 "principale."
 msgstr ""
 
-#: ../../README.md:28
+#: ../../README.md:61
 msgid ""
 "À chaque mise-à-jour de la branche principale, la documentation est "
 "automatiquement compilée et publiée sur le site web de CLUB1."
 msgstr ""
 
-#: ../../README.md:31
+#: ../../README.md:64
 msgid "Langue française"
 msgstr ""
 
-#: ../../README.md:33
+#: ../../README.md:66
 msgid ""
 "Pour modifier une page existante, il faut éditer le fichier `.md` "
 "correspondant. Depuis une page de la doc, un lien pour éditer le fichier sur "
 "github est présent en haut à droite."
 msgstr ""
 
-#: ../../README.md:37
+#: ../../README.md:70
 msgid ""
 "Ajoutez une ligne avec votre nom dans le [fichier `AUTHORS`](https://github."
 "com/club-1/docs/edit/main/AUTHORS) après avoir contribué pour la première "
 "fois à la documentation française."
 msgstr ""
 
-#: ../../README.md:40
+#: ../../README.md:73
 msgid "Autres langues"
 msgstr ""
 
-#: ../../README.md:42
+#: ../../README.md:75
 msgid ""
 "Les traductions, elles, ne sont pas stockées dans des fichiers markdown, "
 "mais dans des fichiers de locales `locales/*/LC_MESSAGES/package.po` et sont "
@@ -97,50 +149,60 @@ msgid ""
 "club-1/docs/)."
 msgstr ""
 
-#: ../../README.md:46
+#: ../../README.md:79
 msgid ""
 "![Translation status](https://hosted.weblate.org/widgets/club-1/-/docs/multi-"
 "auto.svg)"
 msgstr ""
 
-#: ../../README.md:48
+#: ../../README.md:81
 msgid "Ajouter une page"
 msgstr ""
 
-#: ../../README.md:50
+#: ../../README.md:83
 msgid ""
 "L'ajout de pages ne peut se faire qu'en français. Il faut ajouter un fichier "
 "`.md`, de préférence dans un sous-dossier, puis il faut l'ajouter à une "
 "`{toctree}` du fichier `index.html` (s'inpirer de l'existant)."
 msgstr ""
 
-#: ../../README.md:54
+#: ../../README.md:87
 msgid "Références"
 msgstr ""
 
-#: ../../README.md:57
+#: ../../README.md:90
 msgid ""
 "[Fonctionnalités Markdown spécifique à MyST-Parser](https://myst-parser."
 "readthedocs.io/en/latest/syntax/syntax.html)"
 msgstr ""
 
-#: ../../README.md:58
+#: ../../README.md:91
 msgid ""
 "[Spécificités des liens avec Sphinx](https://docs.readthedocs.io/en/stable/"
 "guides/cross-referencing-with-sphinx.html)"
 msgstr ""
 
-#: ../../README.md:59
+#: ../../README.md:92
 msgid ""
 "[Tutoriel de configuration de Sphinx avec le thème ReadTheDocs](https://tech."
 "michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/)"
 msgstr ""
 
-#: ../../README.md:61
+#: ../../README.md:94
 msgid "Compilation"
 msgstr ""
 
-#: ../../README.md:64
+#: ../../README.md:97
+msgid ""
+"Il n'est pas nécessaire de connaître cette section pour participer à "
+"l'édition de la documentation de CLUB1. Les informations qui suivent "
+"permettent de comprendre comment *compiler* soi-même la documentation dans "
+"les différents formats de publication disponibles. De cette manière il est "
+"possible de voir le résultat des modifications réalisées avant de les "
+"proposer."
+msgstr ""
+
+#: ../../README.md:104
 msgid "Prérequis"
 msgstr ""
 
@@ -200,27 +262,27 @@ msgstr ""
 msgid "(Optionnel) Conversion des SVG pour le PDF LaTeX"
 msgstr ""
 
-#: ../../README.md:75
+#: ../../README.md:115
 msgid "Linux basé sur Debian"
 msgstr ""
 
-#: ../../README.md:80
+#: ../../README.md:120
 msgid "Commandes"
 msgstr ""
 
-#: ../../README.md:82
+#: ../../README.md:122
 msgid "Compilation en un site statique dans `_build/html`&nbsp;:"
 msgstr ""
 
-#: ../../README.md:86
+#: ../../README.md:126
 msgid "Compilation d'une locale spécifique&nbsp;:"
 msgstr ""
 
-#: ../../README.md:90
+#: ../../README.md:130
 msgid "Mise-à-jour des locales après l'édition des sources&nbsp;:"
 msgstr ""
 
-#: ../../README.md:94
+#: ../../README.md:134
 msgid ""
 "Toujours vérifier l'état des fichiers `.po` dans `locales` après avoir lancé "
 "l'une de ces commande. Certain passages peuvent ne pas être reconnus si ils "
diff --git a/locales/sphinx.pot b/locales/sphinx.pot
index d0985de..eda6154 100644
--- a/locales/sphinx.pot
+++ b/locales/sphinx.pot
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: CLUB1 main\n"
 "Report-Msgid-Bugs-To: nicolas@club1.fr\n"
-"POT-Creation-Date: 2022-03-29 14:54+0200\n"
+"POT-Creation-Date: 2022-03-30 15:26+0200\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"