mirror of
https://github.com/YunoHost/doc.git
synced 2024-09-03 20:06:26 +02:00
150 lines
6.8 KiB
Markdown
150 lines
6.8 KiB
Markdown
---
|
|
title: Rédaction de la documentation
|
|
template: docs
|
|
taxonomy:
|
|
category: docs
|
|
routes:
|
|
default: '/write_documentation'
|
|
---
|
|
|
|
## Via GitHub
|
|
|
|
La documentation de YunoHost est gérée sur un [dépôt Git](https://github.com/YunoHost/doc).
|
|
|
|
Si vous n'êtes pas familier avec GitHub, il y a un bouton "Éditer" en haut de chaque page qui vous redirigera vers l'éditeur en ligne de GitHub et qui vous aidera à proposer vos modifications (appelées *Pull Requests*, PR).
|
|
|
|
Cependant, si vous êtes lancé sur une série de contributions, vous devriez faire un *fork* du dépôt sur GitHub. Vous pouvez ensuite faire toutes les modifications (*commits*) que vous voulez sur votre dépôt, et les soumettre tous ensemble dans la même PR. L'étiquette sur GitHub vous encouragerait à rassembler dans une même PR tous les *commits* d'une même thématique.
|
|
|
|
Puisque l'éditeur en ligne ne permet pas d'ajouter des fichiers, utiliser Git par la ligne de commande est la méthode recommandée si vous voulez ajouter des médias (comme des images).
|
|
|
|
## Grav
|
|
|
|
Sous le capot, la documentation est déployée avec le [CMS Grav](https://getgrav.org/?target=_blank).
|
|
|
|
La structure du dépôt est décrite ici:
|
|
|
|
```bash
|
|
+-- config
|
|
+-- site.yaml
|
|
+-- system.yaml
|
|
+-- themes
|
|
+-- yunohost-docs.yaml
|
|
# Quelques paramètres pour le thème de la documentation
|
|
+-- images
|
|
# Contains the images used in the documentation pages.
|
|
+-- pages
|
|
# The directory containing the documentation pages.
|
|
# The pages hierarchy is reflected by the directory hierarchy.
|
|
+-- 00.home
|
|
+-- 01.administrate
|
|
+-- 02.applications
|
|
+-- 03.community
|
|
+-- 04.contribute
|
|
+-- themes
|
|
+-- learn4
|
|
+-- yunohost-docs
|
|
# Contient le code du thème, qui est une extension du thème Learn4
|
|
+-- .gitignore
|
|
# Contient les instructions pour ne pas envoyer de fichier
|
|
# sensible ou inutile vers le dépôt Git
|
|
+-- README.md
|
|
```
|
|
|
|
!!!! Pour en apprendre plus sur les fonctionnalités de Grav, vous pouvez consulter sa [documentation](https://learn.getgrav.org?target=_blank) (en anglais). Le reste de cette page donne quelques consignes spécifiques pour contribuer à la documentation de YunoHost.
|
|
|
|
## L'en-tête des pages Grav
|
|
|
|
Chaque page commence par un en-tête qui donne les instructions à Grav sur comment la traiter. Regardons l'en-tête de cette page :
|
|
|
|
```
|
|
---
|
|
title: Rédaction de la documentation
|
|
template: docs
|
|
taxonomy:
|
|
category: docs
|
|
routes:
|
|
default: '/write_documentation'
|
|
---
|
|
|
|
```
|
|
|
|
1. L'en-tête commence et finit par une ligne contenant `---` ;
|
|
2. La clé `title` gère le premier titre de la page, son nom dans le menu de navigation à gauche, et son nom dans l'onglet du navigateur ;
|
|
3. Les clés `template` et `taxonomy` doivent toujours être inclues et laissées telles quelles. Elles informent Grav sur quel thème appliquer aux pages, et permettent de les ordonner correctement.
|
|
4. La clé `routes` et son enfant `default` font que la page est accessible par défaut à l'adresse `https://yunohost.org/docs/write_documentation` au lieu de devoir la chercher à l'adresse `https://yunohost.org/docs/contribute/write_documentation`, qui correspond à son emplacement réel dans la hiérarchie des dossiers.
|
|
|
|
## Syntaxe
|
|
|
|
Vous pouvez utiliser la syntaxe Markdown, consultez la page de [documentation dédiée](/doc_markdown_guide) pour plus d'information.
|
|
|
|
! Notez qu'il ne faut pas préciser le code de langue au début des liens vers d'autres pages de la documentation : `/fr`, `/en`, etc. sont superflus.
|
|
|
|
Pour étendre les fonctionnalités de Markdown, des extensions ont été ajoutées à Grav. Vous pouvez consulter leur propre documentation sur GitHub pour découvrir comment vous en servir.
|
|
```text
|
|
anchors
|
|
external_links
|
|
flex-objects
|
|
highlight
|
|
image-captions
|
|
markdown-notices
|
|
presentation
|
|
presentation-deckset
|
|
shortcode-core
|
|
```
|
|
|
|
## Pages spéciales
|
|
|
|
Quelques pages de la documentation sont générées automatiquement ou dynamiquement.
|
|
|
|
| Page | Chemin | Notes |
|
|
|---------------|--------|-------|
|
|
| Catalogue d'applications | `/pages/02.applications/01.catalog/apps.md` | Récupère et traite le fichier [app.json](https://github.com/YunoHost/apps/blob/master/apps.json?target=_blank) |
|
|
| Apps helpers | `pages/04.contribute/04.packaging_apps/11.helpers/packaging_apps_helpers.md` | Générée par ce [script](https://github.com/YunoHost/yunohost/blob/dev/doc/generate_helper_doc.py?target=_blank), à partir de ce [canevas](https://github.com/YunoHost/yunohost/blob/dev/doc/helper_doc_template.md?target=_blank) |
|
|
| Documentation des apps | `pages/02.applications/02.docs/docs.md` | Liste les sous-pages du même dossier qui ont les clés `taxonomy.category: docs, apps` dans leur en-tête |
|
|
|
|
## Hébergez votre propre documentation de test
|
|
|
|
! Ces instructions ne sont pas encore complètement testées. Aidez-nous en nous rapportant tout problème que vous rencontriez.
|
|
|
|
0. *Fork* le dépôt de la documentation YunoHost sur GitHub
|
|
1. Installez l'app Grav pour YunoHost : `yunohost app install grav`
|
|
2. Installez les extensions suivantes via l'admin ou la ligne de commande de Grav :
|
|
```text
|
|
anchors
|
|
breadcrumbs
|
|
external_links
|
|
feed
|
|
flex-objects
|
|
git-sync
|
|
highlight
|
|
image-captions
|
|
langswitcher
|
|
markdown-notices
|
|
presentation
|
|
presentation-deckset
|
|
shortcode-core
|
|
tntsearch
|
|
```
|
|
3. Paramétrez l'extension Git Sync.
|
|
1. Choisissez `GitHub` et vos identifiants GitHub
|
|
2. Entrez l'adresse de votre *fork*, par exemple `https://github.com/username/doc`
|
|
3. Copiez l'URL du webhook, par exemple `https://grav.example/_git-sync-ca25c111f0de`
|
|
4. "Basic settings" > "Folders to Sync" : `pages` `images` `themes`
|
|
5. "Git Repo Settings" > "User not required" : Enabled
|
|
6. "Git Repo Settings" > "Web Hooks secret" : Enabled
|
|
7. "Advanced settings" > "local branch" : `master`
|
|
8. "Advanced settings" > "remote branch" : `master`
|
|
(vous pouvez changer `master` en une autre branche si vous le souhaitez, mais n'oubliez pas de la créer au préalable sur GitHub)
|
|
9. "Advanced settings" > "Committer Name" : votre nom d'utilisateur sur GitHub
|
|
10. "Advanced settings" > "Committer Email" : votre email renseigné sur GitHub
|
|
11. Enregistrez et cliquez sur "Reset Local Copy"
|
|
12. Renseignez les adresses dans les clés `commits` et `tree` dans `config/themes/yunohost-docs.yaml` pour quelles pointent vers l'adresse de votre *fork* sur GitHub
|
|
4. Assurez-vous que les dossiers `user/pages/01.home` et `user/pages/02.typography` sont supprimés.
|
|
5. Dans l'administration de Grav, dans "Configuration" > "System" :
|
|
1. "Language" > "Supported" : `en` `fr` `de` `es` `ar`
|
|
2. "Language" > "Override Default Language" : `en`
|
|
3. "Language" > "Set language from browser" : `Yes`
|
|
4. "HTTP Headers" > "Etag" : `Yes`
|
|
5. "Advanced" > "Blueprint Compatibility" : `Yes`
|
|
6. "Advanced" > "YAML Compatibility" : `Yes`
|
|
7. "Advanced" > "Twig Compatibility" : `Yes`
|