diff --git a/README.md b/README.md index 28f1a260..31d94298 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@ # YunoHost Documentation * [Web Site](https://yunohost.org) -* Based on [Simone](https://github.com/YunoHost/Simone) +* Based on [Grav](https://getgrav.org/) Please report [issues on YunoHost bugtracker](https://github.com/YunoHost/issues/issues). -You can live test any changes by adding `/edit` to the URL on -[yunohost.org](https://yunohost.org). For example, if you make changes to -[apps.md](./apps.md), you can test them on [yunohost.org/#/apps/edit](https://yunohost.org/#/apps/edit). +# Contributing + +You can refer to the page on [writing documentation](https://yunohost.org/write_documentation). ## Regenerate the css diff --git a/pages/01.administrate/05.install/install.fr.md b/pages/01.administrate/05.install/install.fr.md index 6f1f6e69..f6d22431 100644 --- a/pages/01.administrate/05.install/install.fr.md +++ b/pages/01.administrate/05.install/install.fr.md @@ -168,7 +168,7 @@ Cependant, ces images communautaires existent et sont disponibles sur Docker Hub {% elseif vps_ynh %} * Un serveur dédié ou virtuel avec YunoHost pré-installé, 512Mo de RAM et 16Go de capacité de stockage (au moins) ; {% elseif virtualbox %} -* Un ordinateur x86 avec [VirtualBox installé](https://www.virtualbox.org/wiki/Downloads) et assez de RAM disponible pour lancer une petite machine virtuelle avec 512Mo de RAM et 8Go de capacité de stockage (au moins) ; +* Un ordinateur x86 avec [VirtualBox installé](https://www.virtualbox.org/wiki/Downloads) et assez de RAM disponible pour lancer une petite machine virtuelle avec 1024Mo de RAM et 8Go de capacité de stockage (au moins) ; {% endif %} {% if arm %} * Une alimentation électrique (soit un adaptateur, soit un cable microUSB) pour alimenter la carte ; diff --git a/pages/01.administrate/05.install/install.md b/pages/01.administrate/05.install/install.md index 613dff44..c893de41 100644 --- a/pages/01.administrate/05.install/install.md +++ b/pages/01.administrate/05.install/install.md @@ -168,7 +168,7 @@ However, community images exist and are available on Docker Hub: {% elseif vps_ynh %} * A dedicated or virtual private server with yunohost preinstalled, 512MB RAM and 16GB capacity (at least) {% elseif virtualbox %} -* An x86 computer with [VirtualBox installed](https://www.virtualbox.org/wiki/Downloads) and enough RAM capacity to be able to run a small virtual machine with 512MB RAM and 8GB capacity (at least) +* An x86 computer with [VirtualBox installed](https://www.virtualbox.org/wiki/Downloads) and enough RAM capacity to be able to run a small virtual machine with 1024MB RAM and 8GB capacity (at least) {% endif %} {% if arm %} * A power supply (either an adapter or a MicroUSB cable) for your board; diff --git a/pages/02.applications/04.wishlist/apps_wishlist.md b/pages/02.applications/04.wishlist/apps_wishlist.md index 2c35c614..ee17daa7 100644 --- a/pages/02.applications/04.wishlist/apps_wishlist.md +++ b/pages/02.applications/04.wishlist/apps_wishlist.md @@ -153,6 +153,7 @@ You can [contribute to this list by adding something you'd like to be packaged]( | [Mediagoblin](https://mediagoblin.org/) | Video streaming platform | [Upstream](https://savannah.gnu.org/projects/mediagoblin) | | | [medusa](https://pymedusa.com/) | Automatic TV shows downloader | | [Package Draft](https://github.com/guigot/medusa_ynh) | | [Megaglest](https://megaglest.org/) | realtime stategy game | [Upstream](https://megaglest.org/linux-packages.html) | | +| [Metabase](https://www.metabase.com/) | analytics dashboard | [Upstream](https://github.com/metabase/metabase) | | | microblog.pub | | [Upstream](https://github.com/tsileo/microblog.pub) | | | miniflux | Minimal RSS reader | | [Package Draft](https://github.com/mat-mo/miniflux_ynh) | | [Mirakel](https://mirakel.azapps.de/taskwarrior.html) | | [Upstream](https://github.com/GothenburgBitFactory/taskwarrior) | | diff --git a/pages/04.contribute/02.write_documentation/write_documentation.fr.md b/pages/04.contribute/02.write_documentation/write_documentation.fr.md index 4ab275bc..791b2c12 100644 --- a/pages/04.contribute/02.write_documentation/write_documentation.fr.md +++ b/pages/04.contribute/02.write_documentation/write_documentation.fr.md @@ -7,20 +7,142 @@ routes: default: '/write_documentation' --- -! This page is outdated and should be reworked - -## Sur le site - -Ce site permet d’éditer le contenu directement en ligne. - -Pour éditer une page, appuyez sur la touche `Échap` ou cliquez sur le bouton « Éditer » en bas à droite de la page. Vous pourrez visualiser vos modifications en appuyant de nouveau sur `Échap`, ou en cliquant sur le bouton « Aperçu » en bas à droite de la page. - -Une fois l’édition effectuée, vous pouvez soumettre vos modifications en renseignant un mail. - ## Via GitHub -La documentation de YunoHost est gérée par un [dépot Git](https://github.com/YunoHost/doc). Vous pouvez envoyer des pull-requests. +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*). + +Directement sur GitHub, vous pouvez faire un *fork* du dépôt, y faire vos modifications, et envoyer vos *pull requests*. + +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 -La documentation utilise la syntaxe Markdown. Veuillez vous référer à la [documentation](/doc_markdown_guide) pour plus d’informations. +Vous pouvez utiliser la syntaxe Markdown, consultez la page de [documentation dédiée](/doc_markdown_guide) pour plus d'information. + +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` diff --git a/pages/04.contribute/02.write_documentation/write_documentation.md b/pages/04.contribute/02.write_documentation/write_documentation.md index 755e63bf..7836a4d6 100644 --- a/pages/04.contribute/02.write_documentation/write_documentation.md +++ b/pages/04.contribute/02.write_documentation/write_documentation.md @@ -7,24 +7,143 @@ routes: default: '/write_documentation' --- -! This page is outdated and should be reworked - -## Online - -This site allows to edit content directly online. - -You can edit any page by pressing `ESC` on your keyboard or by clicking the "Edit" button on the bottom-right side of your screen. You will be able to preview your changes by pressing `ESC` again or by clicking the "preview" button. - -To create a new page, you can enter the URL and edit the page from there. - -Once edited, you are able to submit your change by filling an email address. ## Via GitHub -The YunoHost documentation is managed through a [Git repository](https://github.com/YunoHost/doc). You can send pull-requests, and do not forget to report your issues. +The YunoHost documentation is managed through a [Git repository](https://github.com/YunoHost/doc). + +If you are not familiar with GitHub, there is an "Edit" button at the top of each page that will redirect you to the GitHub online editor that will help you making your change proposals (Pull Requests). + +Directly on GitHub, you can fork the repository, make your changes, and send pull requests. Because the online editor doesn't support uploading files, using Git is the prefered way if you need to upload media (e.g. images). +## Grav + +Under the hood, the documentation is served by the [Grav CMS](https://getgrav.org/?target=_blank). + +The structure of the repository is described below: + +```bash ++-- config + +-- site.yaml + +-- system.yaml + +-- themes + +-- yunohost-docs.yaml + # Some settings for the documentation theme ++-- 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 + # Contains the theme's code, which extends Learn4 theme's code ++-- .gitignore + # Contains the instructions to not send sensitive + # or useless files over to the Git repository ++-- README.md +``` + +!!!! To learn more about Grav's features, you can head over to its [documentation](https://learn.getgrav.org?target=_blank). The remainder of this page will show you some specific instructions to contribute to YunoHost's documentation. + +## Grav header + +Each page starts with a header that gives instructions to Grav on how to process them. Let us have a look into the header of this page: + +``` +--- +title: Write documentation +template: docs +taxonomy: + category: docs +routes: + default: '/write_documentation' +--- + +``` + +1. The header starts and ends with a line containing `---` +2. The `title` key manages the first heading title of the page, its name in the navigation menu on the left, and its name in the browser tab +3. `template` and `taxonomy` keys should always be left as is. They instruct Grav to use the proper theme and order the pages properly. +4. `routes`' `default` key makes the page available by default on `https://yunohost.org/docs/write_documentation` instead of needing to reaching it on `https://yunohost.org/docs/contribute/write_documentation`, which is where it is stored in the directory hierarchy. + ## Syntax -This page uses the markdown syntax, please refer to the [documentation](/doc_markdown_guide) for further information. +You can use Markdown syntax, refer to the [documentation](/doc_markdown_guide) for further information. + +To improve Markdown capabilities, additional plugins are installed in Grav. You can refer to their own documentation on GitHub to see how to use them. +```text +anchors +external_links +flex-objects +highlight +image-captions +markdown-notices +presentation +presentation-deckset +shortcode-core +``` + +## Special pages + +Some pages of the documentation are automatically or dynamically generated. + +| Page | Path | Notes | +|---------------|-------|-------| +| Apps catalog | `/pages/02.applications/01.catalog/apps.md` | Retrieves and processes [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` | Generated by this [script](https://github.com/YunoHost/yunohost/blob/dev/doc/generate_helper_doc.py?target=_blank), from this [template](https://github.com/YunoHost/yunohost/blob/dev/doc/helper_doc_template.md?target=_blank) | +| Per-app documentation | `pages/02.applications/02.docs/docs.md` | Lists the subpages in the same directory which have `taxonomy.category: docs, apps` in its header | + +## Host your own testing documentation + +! These instructions are yet to be fully tested. Please help us by reporting any issue you may have with them. + +0. Fork YunoHost documentation repository +1. Install Grav's YunoHost package: `yunohost app install grav` +2. Install the following plugins through Grav's admin panel or CLI: +```text +anchors +breadcrumbs +external_links +feed +flex-objects +git-sync +highlight +image-captions +langswitcher +markdown-notices +presentation +presentation-deckset +shortcode-core +tntsearch +``` +3. Set-up Git Sync plugin. + 1. Choose GitHub and your credentials on GitHub + 2. Set the repo, e.g. `https://github.com/username/doc` + 3. Copy the Webhook's URL, e.g. `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` +(you can change `master` if you want to work on another branch, but do not forget to create it on GitHub first) + 9. Advanced settings > Committer Name: your GitHub username + 10. Advanced settings > Committer Email: your email saved on GitHub + 11. Save and Reset Local Copy + 12. Set `commits` and `tree` keys in `config/themes/yunohost-docs.yaml` to point to your fork's repository +4. Make sure `user/pages/01.home` and `user/pages/02.typography` directories are deleted. +5. 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`