From 98d9ae6bc83c6b57fa4d868a2da1992d051f7606 Mon Sep 17 00:00:00 2001 From: n-peugnet Date: Wed, 6 Apr 2022 17:48:34 +0200 Subject: feat: start using Sphinx specific features - Add a Glossary and start using it - Add an Attention admonition about the specifics of MyST-Parser --- README.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) (limited to 'README.md') 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 . -Elle existe en deux langues : français, la principale et anglais, la secondaire. +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](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 . +```{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 "..."` : ```po #, fuzzy -- cgit v1.2.3