diff options
| -rw-r--r-- | README.md | 25 | ||||
| -rw-r--r-- | conf.py | 2 | ||||
| -rw-r--r-- | general.md | 2 | ||||
| -rw-r--r-- | glossary.md | 24 | ||||
| -rw-r--r-- | index.md | 12 | ||||
| -rw-r--r-- | services/git.md | 6 |
6 files changed, 58 insertions, 13 deletions
@@ -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 : 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 "..."` : ```po #, fuzzy @@ -41,6 +41,8 @@ myst_heading_anchors = 6 myst_enable_extensions = [ # Enable smart quotes at MyST level. 'smartquotes', + # Replace some string patterns (... for instance) with their unicode equivalent. + 'replacements', ] # Add any paths that contain templates here, relative to this directory. @@ -5,7 +5,7 @@ Demandes et Incidents --------------------- Pour toute demande ou incident, veuillez [créer un ticket (_issue_)](https://github.com/club-1/hosting/issues) -sur GitHub (vous devrez pour celà créer un compte), en choisissant entre demande +sur {term}`GitHub` (vous devrez pour cela créer un compte), en choisissant entre demande (_request_) ou incident (_problem_) en fonction de la nature du ticket. Si il s'agit d'une demande impersonnelle, merci de **vérifier** qu'il n'éxiste pas déjà une demande similaire à l'aide de la barre de recherche. diff --git a/glossary.md b/glossary.md new file mode 100644 index 0000000..81eab5e --- /dev/null +++ b/glossary.md @@ -0,0 +1,24 @@ +(glossary)= + +Glossaire +========= + +```{glossary} +--- +sorted: +--- + +Git + Logiciel de gestion de versions décentralisé. --- + [Wikipedia](https://fr.wikipedia.org/wiki/Git) + +GitHub + Service web d'hébergement et de gestion de développement de logiciels, + utilisant le logiciel de gestion de versions {term}`Git`. --- + [Wikipedia](https://fr.wikipedia.org/wiki/GitHub) + +markdown + Language de balisage léger permettant de mettre en forme un document. --- + [Wikipedia](https://fr.wikipedia.org/wiki/Markdown) + +``` @@ -8,4 +8,16 @@ maxdepth: 2 general services/index interne/index +glossary +``` + + +```{eval-rst} +.. only:: html + + Indexes et tables + ================= + + - :ref:`genindex` + - :ref:`glossary` ``` diff --git a/services/git.md b/services/git.md index 615d8cc..ead5453 100644 --- a/services/git.md +++ b/services/git.md @@ -2,7 +2,7 @@ Dépôts Git publics ================== Le dossier `git/`, à la racine de l'**espace personnel** est particulier. -Les dépôts Git rangés dedans seront automatiquement publiés en _lecture seule_ +Les dépôts {term}`Git` rangés dedans seront automatiquement publiés en _lecture seule_ à l'adresse `https://git.club1.fr`, par exemple : [`https://git.club1.fr/nicolas/dna-backup/`](https://git.club1.fr/nicolas/dna-backup/) @@ -18,7 +18,7 @@ Cette adresse permet 2 choses : Tutoriel d'utilisation ---------------------- -Pour utiliser la fonctionnalité de dépôts Git publics sur CLUB1, il faut tout +Pour utiliser la fonctionnalité de dépôts {term}`Git` publics sur CLUB1, il faut tout d'abord initialiser le dépôt à distance, avec [SSH](ssh.md), depuis un ordinateur personnel (remplacer `<login>` par votre **identifiant** et `<repo>` par le nom que vous voulez donner au dépôt) : @@ -57,7 +57,7 @@ qui est normal : warning: You appear to have cloned an empty repository. -Il est désormais possible d'utiliser ce dépôt comme tout autre dépôt Git, +Il est désormais possible d'utiliser ce dépôt comme tout autre dépôt {term}`Git`, par exemple : cd <repo> |