feat: start using Sphinx specific features

- Add a Glossary and start using it
- Add an Attention admonition about the specifics of MyST-Parser

1 files changed, 16 insertions, 9 deletions

diff --git a/README.md b/README.md
index 970d58f..9351f38 100644
--- a/README.md
+++ b/README.md
@@ -5,14 +5,22 @@ Meta-documentation
 [![Translation status][transimg]][transurl]
 
 La documentation de CLUB1 est publiée au format HTML à l'adresse <https://club1.fr/docs/fr/>.
-Elle existe en deux langues : français, la principale et anglais, la secondaire.
+Elle existe en deux langues&nbsp;: 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](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)
+à partir de fichiers source écrits en {term}`markdown`.
+Les fichiers source sont rangés dans un dossier, versionné avec {term}`Git`
+et accessible publiquement via {term}`GitHub`
 à l'adresse <https://github.com/club-1/docs/>.
 
+```{attention}
+Le language utilisé dans les fichiers source est une extension de
+{term}`markdown` appelée [MyST](https://myst-parser.readthedocs.io/en/latest/).
+Il apporte donc quelques spécificités supplémentaires, comme expliqué dans
+leur [guide syntaxique](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html),
+dont il existe aussi une [référence rapide](https://myst-parser.readthedocs.io/en/latest/syntax/reference.html).
+```
+
 Arborescence du dossier
 -----------------------
 
@@ -50,8 +58,8 @@ documentation.
 Proposer des modifications
 --------------------------
 
-L'utilisation de Git permet à n'importe qui de proposer des modifications.
-Pour cela il est possible de modifier les fichiers directement sur GitHub
+L'utilisation de {term}`Git` permet à n'importe qui de proposer des modifications.
+Pour cela il est possible de modifier les fichiers directement sur {term}`GitHub`
 (un compte sera nécessaire), dans une branche personnelle, puis de créer
 une _pull request_ vers la branche principale: `main` (il s'agit de l'action
 proposée par défaut).
@@ -64,7 +72,7 @@ automatiquement compilée et publiée sur le site web de CLUB1.
 ### Langue française
 
 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
+Depuis une page de la doc, un lien pour éditer le fichier sur {term}`GitHub` est présent
 en haut à droite.
 
 Ajoutez une ligne avec votre nom dans le [fichier `AUTHORS`](https://github.com/club-1/docs/edit/main/AUTHORS)
@@ -87,7 +95,6 @@ fichier `index.html` (s'inpirer de l'existant).
 Références
 ----------
 
-- [Fonctionnalités Markdown spécifique à MyST-Parser](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html)
 - [Spécificités des liens avec Sphinx](https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html)
 - [Tutoriel de configuration de Sphinx avec le thème ReadTheDocs](https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/)
 
@@ -135,7 +142,7 @@ 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 ont
 trop changé, il faudra peut-être en récupérer la traduction dans les messages
 mis en commentaire à la fin du fichier, tout en ajoutant le commentaire suivant
-juste au dessus du la ligne `msgid "..."` :
+juste au dessus du la ligne `msgid "..."`&nbsp;:
 
 ```po
 #, fuzzy