mirror of
https://github.com/YunoHost/doc.git
synced 2024-09-03 20:06:26 +02:00
Merge pull request #1216 from Plumf/dev-redact-doc
Ajout guide d'accompagnement de nouveau contributeurs⋅trices
This commit is contained in:
Plumf
GitHub
commit
e2984c9783
13 changed files with 875 additions and 7 deletions
|
|
@ -1,5 +1,74 @@
|
|||
===== Pihole =====
|
||||
# <img src="/images/pihole_logo.png" width="80px" alt="Pi-hole's logo"> Pi-hole
|
||||
|
||||
Homepage: https://pi-hole.net
|
||||
[](https://install-app.yunohost.org/?app=pihole) [](https://dash.yunohost.org/appci/app/pihole)
|
||||
|
||||
**Pi-hole®** Network-wide ad blocking via your own DNS server, with nice Performance And Statistics web page.
|
||||
### Index
|
||||
|
||||
- [Using Pi-Hole as a DHCP server](#using-pi-hole-as-a-dhcp-server)
|
||||
- [Configure Pi-Hole](#configure-pi-hole)
|
||||
- [Configure my router](#configure-my-router)
|
||||
- [Restore Network](#restore-network)
|
||||
- [Useful links](#useful-links)
|
||||
|
||||
Pi-hole is a network-level ad blocker that acts as a DNS layer and possibly a DHCP3 server for use on a private network. It is designed to be installed on embedded devices with network capabilities, such as the Raspberry Pi, but can be used on other machines running Linux or in virtualised environments.
|
||||
|
||||
## Using Pi-Hole as a DHCP server
|
||||
|
||||
> **Warning, you should be aware that touching your DHCP could break your network.
|
||||
In case your server is inaccessible, you will lose your dns resolution and IP address.
|
||||
Thus, you would lose any connection to the internet and even the connection to your router.**
|
||||
|
||||
> If you encounter this kind of problem, please read the section "How to restore my network".
|
||||
|
||||
### Configure Pi-Hole
|
||||
|
||||
There are 2 ways to configure Pi-hole to be used as your DHCP server.
|
||||
- Either you can choose to use it when you install the application.
|
||||
- Or you can activate the DHCP server afterwards in the "Settings" tab, part "Pi-hole DHCP Server".
|
||||
In this second case, it may be preferable to force the server IP to a static address.
|
||||
|
||||
### Configure my router
|
||||
|
||||
Your router or your ISP's router has a DHCP server enabled by default.
|
||||
If you keep this DHCP, along with Pi-hole's, you will have transparent conflicts between them.
|
||||
The first DHCP server to respond will distribute its own IP and settings.
|
||||
So you need to turn off your router's DHCP server and let Pi-hole manage your network.
|
||||
|
||||
#### Why should I use Pi-hole's DHCP?
|
||||
|
||||
By using Pi-hole's DHCP, you allow Pi-hole to give its dns configuration to each of your clients. This way, every request will be filtered by Pi-hole.
|
||||
|
||||
Another case of using Pi-hole DHCP is if you have hairpinning problems (you can't connect to your server because its IP is your public IP, and your router doesn't allow this).
|
||||
In this case, using Pi-hole's dns will allow you to connect to your server by its local address rather than its public address.
|
||||
|
||||
### Restore network
|
||||
|
||||
> Oops!
|
||||
Your Pi-hole server has crashed, and you don't have DHCP anymore.
|
||||
Don't panic. We'll get through this.
|
||||
|
||||
Use your favorite device on your desktop computer.
|
||||
And first, get your network interface (usually `eth0`).
|
||||
```bash
|
||||
sudo ifconfig
|
||||
```
|
||||
|
||||
Then change your IP to a static one.
|
||||
```bash
|
||||
sudo ifconfig eth0 192.168.1.100
|
||||
```
|
||||
|
||||
Now you can connect to your router and reboot its DHCP server to use it again.
|
||||
You can now remove your static IP and get a dynamic IP again.
|
||||
```bash
|
||||
sudo ifconfig eth0 0.0.0 && sudo dhclient eth0
|
||||
```
|
||||
|
||||
> Remember to turn off your router's DHCP if your server is running again.
|
||||
|
||||
## Useful links
|
||||
|
||||
+ Website: [pi-hole.net](https://pi-hole.net)
|
||||
+ Official documentation: [docs.pi-hole.net](https://docs.pi-hole.net/)
|
||||
+ Application software repository: [github.com - YunoHost-Apps/pihole](https://github.com/YunoHost-Apps/pihole_ynh)
|
||||
+ Fix a bug or an improvement by creating a ticket (issue): [github.com - YunoHost-Apps/pihole/issues](https://github.com/YunoHost-Apps/pihole_ynh/issues)
|
||||
|
|
|
|||
|
|
@ -1,5 +1,72 @@
|
|||
# Pihole
|
||||
# <img src="/images/pihole_logo.png" alt="logo de Pi-hole"> Pi-hole
|
||||
|
||||
Page d'accueil : https://pi-hole.net
|
||||
[](https://install-app.yunohost.org/?app=pihole)[](https://dash.yunohost.org/appci/app/pihole)
|
||||
|
||||
**Pi-hole®** Blocage des publicités à l'échelle du réseau via votre propre serveur DNS, avec une belle page web Performance And Statistics.
|
||||
- [Utiliser Pi-Hole comme serveur DHCP](#utiliser-pi-hole-comme-serveur-dhcp)
|
||||
- [Configurer Pi-Hole](#configurer-pi-hole)
|
||||
- [Configurer mon routeur](#configurer-mon-routeur)
|
||||
- [Restaurer le réseau](#restaurer-le-réseau)
|
||||
- [Liens utiles](#liens-utiles)
|
||||
|
||||
Pi-hole est un bloqueur de publicité au niveau du réseau qui agit comme un DNS menteur et éventuellement un serveur DHCP3, destiné à être utilisé sur un réseau privé. Il est conçu pour être installé sur des périphériques intégrés dotés de capacités réseau, tels que le Raspberry Pi, mais il peut être utilisé sur d'autres machines exécutant Linux ou dans des environnements virtualisés.
|
||||
|
||||
## Utiliser Pi-Hole comme serveur DHCP
|
||||
|
||||
> **Attention, vous devez savoir que toucher à votre DHCP pourrait casser votre réseau.
|
||||
Dans le cas où votre serveur serait inaccessible, vous perdriez votre résolution dns et votre adresse IP.
|
||||
Ainsi, vous perdriez toute connexion à internet et même la connexion à votre routeur.**
|
||||
|
||||
> **Si vous rencontrez ce genre de problèmes, merci de lire la section "Comment restaurer mon réseau".**
|
||||
|
||||
### Configurer Pi-hole
|
||||
|
||||
Il y a 2 manière de configurer Pi-hole pour qu'il soit utilisé comme votre serveur DHCP.
|
||||
- Soit vous pouvez choisir de l'utiliser lorsque vous installez l'application.
|
||||
- Soit vous pouvez activer le serveur DHCP par la suite dans l'onglet "Settings", partie "Pi-hole DHCP Server".
|
||||
Dans ce second cas, il peut être préférable de forcer l'ip du serveur à une adresse statique.
|
||||
|
||||
### Configurer mon routeur
|
||||
|
||||
Votre routeur ou celui de votre FAI dispose d'un serveur DHCP activé par défaut.
|
||||
Si vous gardez ce DHCP, en même temps que celui de Pi-hole, vous allez avoir des conflits transparents entre eux.
|
||||
Le premier serveur DHCP à répondre va distribuer ses propres ip et paramètres.
|
||||
Donc vous devez éteindre le serveur DHCP de votre routeur et laisser Pi-hole gérer votre réseau.
|
||||
|
||||
#### Pourquoi je devrais utiliser le DHCP de Pi-hole ?
|
||||
|
||||
En utilisant le DHCP de Pi-hole, vous lui permettez de donner sa configuration dns à chacun de vos clients. De cette manière, chaque requête sera filtrée par Pi-hole.
|
||||
|
||||
Un autre cas d'usage du DHCP de Pi-hole est le cas où vous rencontrez des problèmes de hairpinning (Vous ne pouvez pas vous connecter à votre serveur parce que son ip est votre ip publique, et votre routeur n'autorise pas cela).
|
||||
Dans ce cas, utilisez le dns de Pi-hole va vous permettre de vous connecter à votre serveur par son adresse locale plutôt que son adresse publique.
|
||||
|
||||
### Restaurer le réseau
|
||||
|
||||
> Oups !
|
||||
Votre serveur Pi-hole est tombé, et vous n'avez plus de DHCP.
|
||||
Ne paniquez pas, on va surmonter ça \o/
|
||||
|
||||
Utilisez votre terminal favori sur votre ordinateur de bureau.
|
||||
Et tout d'abord, récupérer votre interface réseau (Le plus souvent `eth0`).
|
||||
``` bash
|
||||
sudo ifconfig
|
||||
```
|
||||
|
||||
Ensuite, changer votre ip pour une ip statique.
|
||||
``` bash
|
||||
sudo ifconfig eth0 192.168.1.100
|
||||
```
|
||||
|
||||
Maintenant, vous pouvez vous connecter à votre routeur et rallumer son serveur DHCP pour l'utiliser à nouveau.
|
||||
Vous pouvez maintenant retirer votre ip statique et réobtenir une ip dynamique.
|
||||
``` bash
|
||||
sudo ifconfig eth0 0.0.0.0 && sudo dhclient eth0
|
||||
```
|
||||
|
||||
> N'oubliez pas d'éteindre le DHCP de votre routeur si votre serveur fonctionne à nouveau.
|
||||
|
||||
## Liens utiles
|
||||
|
||||
+ Site web : [pi-hole.net (en)](https://pi-hole.net)
|
||||
+ Documentation officielle : [docs.pi-hole.net (en)](https://docs.pi-hole.net/)
|
||||
+ Dépôt logiciel de l'application : [github.com - YunoHost-Apps/pihole](https://github.com/YunoHost-Apps/pihole_ynh)
|
||||
+ Remonter un bug ou une amélioration en créant un ticket (issue) : [github.com - YunoHost-Apps/pihole/issues](https://github.com/YunoHost-Apps/pihole_ynh/issues)
|
||||
|
|
|
|||
33
app_writing_guide.md
Normal file
33
app_writing_guide.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
# <img src="/images/APPLICATION_logo.svg" width="80px" alt="APPLICATION's logo"> APPLICATION
|
||||
|
||||
[](https://install-app.yunohost.org/?app=APPLICATION) [](https://dash.yunohost.org/appci/app/APPLICATION)
|
||||
|
||||
### Index
|
||||
|
||||
- [Configuration](#configuration)
|
||||
- [Limitations of YunoHost](#limitations-with-yunohost)
|
||||
- [Customer Applications](#customer-applications)
|
||||
- [Useful links](#useful-links)
|
||||
|
||||
**General presentation of the application.** *Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce rutrum sodales mauris eu viverra. Sed dapibus, tellus sit amet interdum condimentum, enim eros faucibus ligula, sed suscipit orci velit at felis. Etiam quam lacus, vulputate eu scelerisque ac, sollicitudin rutrum orci. Cras eu ante porttitor, laoreet odio sed, hendrerit tellus. Nulla luctus sem in arcu scelerisque cursus. Nulla ut tellus at leo porttitor tincidunt. Morbi vitae purus convallis, elementum lectus non, dignissim orci. Integer eget egestas mauris. Nunc nunc dolor, cursus in quam mollis, rutrum fermentum nibh. Aliquam molestie velit a nulla porttitor, sit amet tincidunt erat laoreet.*
|
||||
|
||||
## Configuration
|
||||
|
||||
**If the configuration of the application is not done with the admin panel of YunoHost.** *Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce rutrum sodales mauris eu viverra. Sed dapibus, tellus sit amet interdum condimentum, enim eros faucibus ligula, sed suscipit orci velit at felis. Etiam quam lacus, vulputate eu scelerisque ac, sollicitudin rutrum orci. Cras eu ante porttitor, laoreet odio sed, hendrerit tellus. Nulla luctus sem in arcu scelerisque cursus. Nulla ut tellus at leo porttitor tincidunt. Morbi vitae purus convallis, elementum lectus non, dignissim orci. Integer eget egestas mauris. Nunc nunc dolor, cursus in quam mollis, rutrum fermentum nibh. Aliquam molestie velit a nulla porttitor, sit amet tincidunt erat laoreet.*
|
||||
|
||||
## Limitations with YunoHost
|
||||
|
||||
**Explanation of the current limitations in using the application with YunoHost.** *Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce rutrum sodales mauris eu viverra. Sed dapibus, tellus sit amet interdum condimentum, enim eros faucibus ligula, sed suscipit orci velit at felis. Etiam quam lacus, vulputate eu scelerisque ac, sollicitudin rutrum orci. Cras eu ante porttitor, laoreet odio sed, hendrerit tellus. Nulla luctus sem in arcu scelerisque cursus. Nulla ut tellus at leo porttitor tincidunt. Morbi vitae purus convallis, elementum lectus non, dignissim orci. Integer eget egestas mauris. Nunc nunc dolor, cursus in quam mollis, rutrum fermentum nibh. Aliquam molestie velit a nulla porttitor, sit amet tincidunt erat laoreet.*
|
||||
|
||||
## Customer applications
|
||||
|
||||
| Application name | Platform | Multi-account | Other supported networks | Play Store | F-Droid | Apple Store | *Other* |
|
||||
|------------------|----------|---------------|--------------------------|------------|---------|-------------|---------|
|
||||
| | | | | | | | |
|
||||
|
||||
## Useful links
|
||||
|
||||
+ Website: [WEBSITE](#)
|
||||
+ Official documentation: [DOCUMENTATION](#)
|
||||
+ Application software repository: [github.com - YunoHost-Apps/APPLICATION](https://github.com/YunoHost-Apps/APPLICATION_ynh)
|
||||
+ Fix a bug or an improvement by creating a ticket (issue): [github.com - YunoHost-Apps/APPLICATION/issues](https://github.com/YunoHost-Apps/APPLICATION_ynh/issues)
|
||||
33
app_writing_guide_fr.md
Normal file
33
app_writing_guide_fr.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
# <img src="/images/APPLICATION_logo.svg" width="80px" alt="logo de APPLICATION"> APPLICATION
|
||||
|
||||
[](https://install-app.yunohost.org/?app=APPLICATION) [](https://dash.yunohost.org/appci/app/APPLICATION)
|
||||
|
||||
### Index
|
||||
|
||||
- [Configuration](#configuration)
|
||||
- [Limitations avec YunoHost](#limitations-avec-yunohost)
|
||||
- [Applications clientes](#applications-clientes)
|
||||
- [Liens utiles](#liens-utiles)
|
||||
|
||||
**Présentation générale de l'application.** *Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce rutrum sodales mauris eu viverra. Sed dapibus, tellus sit amet interdum condimentum, enim eros faucibus ligula, sed suscipit orci velit at felis. Etiam quam lacus, vulputate eu scelerisque ac, sollicitudin rutrum orci. Cras eu ante porttitor, laoreet odio sed, hendrerit tellus. Nulla luctus sem in arcu scelerisque cursus. Nulla ut tellus at leo porttitor tincidunt. Morbi vitae purus convallis, elementum lectus non, dignissim orci. Integer eget egestas mauris. Nunc nunc dolor, cursus in quam mollis, rutrum fermentum nibh. Aliquam molestie velit a nulla porttitor, sit amet tincidunt erat laoreet.*
|
||||
|
||||
## Configuration
|
||||
|
||||
**Si la configuration de l'application ne se fait pas avec le panel admin de YunoHost.** *Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce rutrum sodales mauris eu viverra. Sed dapibus, tellus sit amet interdum condimentum, enim eros faucibus ligula, sed suscipit orci velit at felis. Etiam quam lacus, vulputate eu scelerisque ac, sollicitudin rutrum orci. Cras eu ante porttitor, laoreet odio sed, hendrerit tellus. Nulla luctus sem in arcu scelerisque cursus. Nulla ut tellus at leo porttitor tincidunt. Morbi vitae purus convallis, elementum lectus non, dignissim orci. Integer eget egestas mauris. Nunc nunc dolor, cursus in quam mollis, rutrum fermentum nibh. Aliquam molestie velit a nulla porttitor, sit amet tincidunt erat laoreet.*
|
||||
|
||||
## Limitations avec YunoHost
|
||||
|
||||
**Explication des limitations actuelles en utilisation l'application avec YunoHost.** *Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce rutrum sodales mauris eu viverra. Sed dapibus, tellus sit amet interdum condimentum, enim eros faucibus ligula, sed suscipit orci velit at felis. Etiam quam lacus, vulputate eu scelerisque ac, sollicitudin rutrum orci. Cras eu ante porttitor, laoreet odio sed, hendrerit tellus. Nulla luctus sem in arcu scelerisque cursus. Nulla ut tellus at leo porttitor tincidunt. Morbi vitae purus convallis, elementum lectus non, dignissim orci. Integer eget egestas mauris. Nunc nunc dolor, cursus in quam mollis, rutrum fermentum nibh. Aliquam molestie velit a nulla porttitor, sit amet tincidunt erat laoreet.*
|
||||
|
||||
## Applications clientes
|
||||
|
||||
| Nom de l'applications | Plateforme | Multi-comptes | Autre réseaux supportés | Play Store | F-Droid | Apple Store | *Autres* |
|
||||
|-----------------------|------------|---------------|-------------------------|------------|---------|-------------|----------|
|
||||
| | | | | | | | |
|
||||
|
||||
## Liens utiles
|
||||
|
||||
+ Site web : [SITE WEB](#)
|
||||
+ Documentation officielle : [DOCUMENTATION](#)
|
||||
+ Dépôt logiciel de l'application : [github.com - YunoHost-Apps/APPLICATION](https://github.com/YunoHost-Apps/APPLICATION_ynh)
|
||||
+ Remonter un bug ou une amélioration en créant un ticket (issue) : [github.com - YunoHost-Apps/APPLICATION/issues](https://github.com/YunoHost-Apps/APPLICATION_ynh/issues)
|
||||
|
|
@ -2,6 +2,9 @@
|
|||
|
||||
* [General ways of contributing to YunoHost](/contribute)
|
||||
* [Writing documentation](/write_documentation)
|
||||
* [Documentation wrinting guide](/doc_writing_guide)
|
||||
* [Markdown guide](/doc_markdown_guide)
|
||||
* [Propulser son code avec Git & GitHub](/doc_use_git)
|
||||
* [Chat rooms](/chat_rooms)
|
||||
* Application packaging
|
||||
* [Apps wishlist](/apps_wishlist)
|
||||
|
|
|
|||
|
|
@ -2,9 +2,12 @@
|
|||
|
||||
* [Liste des façons de contribuer à YunoHost](/contribute)
|
||||
* [Écrire de la documentation](/write_documentation)
|
||||
* [Guide de redaction de la documentation](/doc_writing_guide)
|
||||
* [Guide Markdown](/doc_markdown_guide)
|
||||
* [Propulser son code avec Git & GitHub](/doc_use_git)
|
||||
* [Salons de discussion](/chat_rooms)
|
||||
* Packaging d'application
|
||||
* [Liste d'apps souhaitées par la communauté](/apps_wishlist)
|
||||
* [Liste d'applications souhaitées par la communauté](/apps_wishlist)
|
||||
* [Introduction générale au packaging d'apps](/packaging_apps_start)
|
||||
* [Introduction technique au packaging d'apps](/packaging_apps)
|
||||
* [Comment utiliser Git pour packager les applications](/packaging_apps_git)
|
||||
|
|
|
|||
252
doc_markdown_guide.md
Normal file
252
doc_markdown_guide.md
Normal file
|
|
@ -0,0 +1,252 @@
|
|||
# Guide Markdown
|
||||
|
||||
Markdown is a markup language created in 2004, many add-ons developing the possibilities of this language exist. The objective of this guide is to aim for the exhaustiveness of the possibilities of this formatting language within the framework of the YunoHost documentation and not Markdown languages in general.
|
||||
|
||||
Markdown allows text to be formatted using tags, it allows *human* reading of the text; even with formatting. Even if only one notepad is needed there are many markdowns software (Markdown on [framalibre.org (fr)](https://framalibre.org/recherche-par-crit-res?keys=markdown)). It is relatively easy to use.
|
||||
|
||||
## The different levels of titles
|
||||
|
||||
By writing titles as follows:
|
||||
```Markdown
|
||||
# Level 1 title
|
||||
## Level 2 title
|
||||
### Level 3 title
|
||||
#### Level 4 title
|
||||
##### Level 5 title
|
||||
###### Level 6 title
|
||||
```
|
||||
|
||||
They appear like this:
|
||||
# Level 1 title
|
||||
## Level 2 title
|
||||
### Level 3 title
|
||||
#### Level 4 title
|
||||
##### Level 5 title
|
||||
###### Level 6 title
|
||||
|
||||
## Formatting in paragraphs
|
||||
|
||||
To type a line break without creating a new paragraph, it is necessary to type **two consecutive spaces**. Otherwise, the text will continue in a row respecting the general constraints of the page style.
|
||||
|
||||
By writing this :
|
||||
|
||||
```markdown
|
||||
For text in *italic you have to frame it with an asterisk* `*`
|
||||
To write **bold text by two asterisks** `**`
|
||||
You can also ~~bar the text~~ by framing it with two tildes `~`
|
||||
```
|
||||
|
||||
It reads like this:
|
||||
|
||||
For text in *italic you have to frame it with an asterisk* `*`
|
||||
To write **bold text by two asterisks** `**`
|
||||
You can also ~~bar the text~~ by framing it with two tildes `~`
|
||||
|
||||
## Create links
|
||||
|
||||
To create a link to a site outside of the YunoHost documentation:
|
||||
|
||||
```markdown
|
||||
[Text to display](https://lelien.tld)
|
||||
```
|
||||
|
||||
will be displayed as such:
|
||||
[Text to display](https://lelien.tld)
|
||||
|
||||
It is the same for the documentation pages, except that the link is internal. It refers to the wiki file, without language and file extension (the `_fr.md`) :
|
||||
```markdown
|
||||
[Wiki Page](/write_documentation)
|
||||
```
|
||||
|
||||
The link will return to the page with the correct language setting if the page exists.
|
||||
[Wiki page](/write_documentation)
|
||||
|
||||
### Create anchors
|
||||
An anchor allows you to make a link to a specific point in a page, that's how the indexes at the top of the page work. To create an anchor, you need to insert code at the anchor location in the following form :
|
||||
|
||||
```markdown
|
||||
Text that will be doesn't even know it has an anchor.
|
||||
```
|
||||
|
||||
What's displayed is:
|
||||
Text that will be doesn't even know it has an anchor.
|
||||
|
||||
It is also possible to return an anchor directly to the title, noting the link in lower case with `-`s instead of spaces.
|
||||
All that remains is to designate the anchor to the text you want to make interactive:
|
||||
|
||||
```markdown
|
||||
[My Anchor Returns to Lists](#anchorname)
|
||||
[My Anchor that refers to the title of the tables](#tables)
|
||||
```
|
||||
|
||||
[My Anchor Returns to Lists](#anchorame)
|
||||
[My Anchor that refers to the title of the tables](#tables)
|
||||
|
||||
## Displaying images
|
||||
|
||||
To display images, the principle is the same as for links, except that a `!` is added before the text to be displayed, which is considered here as the text to be displayed if the image cannot be loaded. A description of the image is appropriate.
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
It is possible to make a link with an image, for example :
|
||||
```markdown
|
||||
[](/write_documentation)
|
||||
```
|
||||
[](/write_documentation)
|
||||
|
||||
The insert of *text to be displayed if the image cannot be loaded* between the brackets in the image link is not mandatory but strongly recommended.
|
||||
|
||||
## Format a quote
|
||||
|
||||
Quotes are used to highlight a statement made by another person, the wiki itself manages the way it is highlighted. Markdown uses a closing chevron, this symbol: `>`, to announce a quote. Just add it before the quote, as such:
|
||||
|
||||
```markdown
|
||||
>First level quotation text
|
||||
>which can be formatted in different lines
|
||||
|
||||
>> And a second quote
|
||||
>> with double rafters
|
||||
```
|
||||
Will be displayed :
|
||||
|
||||
>First level quotation text
|
||||
>which can be formatted in different lines
|
||||
|
||||
>> And a second quote
|
||||
>> with double rafters
|
||||
|
||||
## Lists
|
||||
|
||||
Lists allow to display a series of texts in an easy presentation, this is how indexes such as the [contributing documentation](/contributordoc) page are written.
|
||||
|
||||
### Ordered lists
|
||||
|
||||
The ordered lists can be incremented as much as you wish, it is not necessary to give the right match to the number. It is possible to write down with `1.` and put in three spaces to mark the increment. For a better understanding of the plain text, it may be fine to use the numbers in ascending order to mark the increment, but it is the three consistent `spaces' before the sub-list that will mark the increment.
|
||||
|
||||
```markdown
|
||||
1. List 1
|
||||
1. List 2
|
||||
1. list 3
|
||||
1. List 3a
|
||||
1. List 3b
|
||||
1. List 3b1
|
||||
1. List 3b2
|
||||
1. List 3b3
|
||||
1. List 1
|
||||
1. List 2
|
||||
1. list 3
|
||||
1. List 4
|
||||
1. List 5
|
||||
1. list 6
|
||||
```
|
||||
|
||||
You get:
|
||||
|
||||
1. List 1
|
||||
1. List 2
|
||||
1. list 3
|
||||
1. List 3a
|
||||
1. List 3b
|
||||
1. List 3b1
|
||||
1. List 3b2
|
||||
1. List 3b3
|
||||
1. List 1
|
||||
1. List 2
|
||||
1. list 3
|
||||
5. List 4
|
||||
3. List 5
|
||||
4. list 6
|
||||
|
||||
### Unordered lists<a name="anchorname"></a>
|
||||
|
||||
To create an unordered list, use the symbols `*`, `+` or `*`. This will not change the appearance of the marker in the text output. It is the incrementing of the list that will define the visual. For a better reading of the plain text, it may be good to use the different symbols to mark the increment, but it is the three spaces before the sub-list that will indicate the increment.
|
||||
As such:
|
||||
```markdown
|
||||
+ List 1
|
||||
+ List 2
|
||||
+ list 3
|
||||
- List 3a
|
||||
- List 3b
|
||||
* List 3b1
|
||||
* List 3b2
|
||||
* List 3b3
|
||||
+ List 1
|
||||
+ List 2
|
||||
+ list 3
|
||||
- List 4
|
||||
* List 5
|
||||
+ list 6
|
||||
```
|
||||
|
||||
This will read:
|
||||
+ List 1
|
||||
+ List 2
|
||||
+ list 3
|
||||
- List 3a
|
||||
- List 3b
|
||||
* List 3b1
|
||||
* List 3b2
|
||||
* List 3b3
|
||||
+ List 1
|
||||
+ List 2
|
||||
+ list 3
|
||||
- List 4
|
||||
* List 5
|
||||
+ list 6
|
||||
|
||||
## Tables
|
||||
|
||||
To create an array, use the vertical bar `|` and dashes `--`. It is mandatory to add a line of dashes under the first line of the table. There is no constraint in the size of the table. It is possible to format the array with the `:` in the second row of the array, three options are available:
|
||||
|
||||
| Left aligned column | Centered column | Right aligned column |
|
||||
|:--------------------|:---------------:|---------------------:|
|
||||
|`:-----` | `:----:` | `-----:` |
|
||||
|
||||
```markdown
|
||||
| **One table** | One column | One second | As many as you want |
|
||||
|:-------------:|:----------:|:----------:|:-------------------:|
|
||||
| | And formatted line | | And bold text | | Or *italic* |
|
||||
| More lines | | | [Or a link](/contributordoc) |
|
||||
```
|
||||
Which would say this:
|
||||
|
||||
| **One table** | One column | One second | As many as you want |
|
||||
|:-------------:|:----------:|:----------:|:-------------------:|
|
||||
| | And formatted line | | And bold text | | Or *italic* |
|
||||
| More lines | | | [Or a link](/contributordoc) |
|
||||
|
||||
## Code block
|
||||
|
||||
To display plain text, `blocks of code' can be created using the grave accent `Alt Gr + è` :
|
||||
|
||||
```markdown
|
||||
Either inline, for example to highlight a key like `Ctrl`.
|
||||
```
|
||||
|
||||
or directly as a block.
|
||||
The only difference is in the amount of bass accents:
|
||||
At least three low pitched accents at the opening and closing of the block and two low pitched accents that frame the piece of text to be formatted in a line.
|
||||
|
||||
Which will give the rendering:
|
||||
|
||||
Either inline, for example to highlight a key like `Ctrl`.
|
||||
'''
|
||||
```markdown
|
||||
or directly as a block.
|
||||
The only difference is in the amount of bass accents:
|
||||
At least three low pitched accents at the opening and closing of the block and two low pitched accents that frame the piece of text to be formatted in a line.
|
||||
```
|
||||
'''
|
||||
|
||||
## Useful links
|
||||
|
||||
+ The documentation of the original Markdown language: [daringfireball.net/projects/markdown](https://daringfireball.net/projects/markdown/)
|
||||
+ Markdown Tutorial on [markdowntutorial.com](https://markdowntutorial.com)
|
||||
|
||||
## Going further
|
||||
|
||||
In a more general way, to understand how a text is formatted just inspect the source document with a note application. This does not mean that the YunoHost wiki will be able to exploit it. There are many other possibilities to use markdown syntax, feel free to add missing features. If you've noticed some missing features and/or have questions, please contact us on [the forum](https://forum.yunohost.org) or by direct message on the IRC room: **#yunohost** on [irc.freenode.net](https://irc.freenode.net).
|
||||
251
doc_markdown_guide_fr.md
Normal file
251
doc_markdown_guide_fr.md
Normal file
|
|
@ -0,0 +1,251 @@
|
|||
# Guide Markdown
|
||||
|
||||
Le Markdown est un langage de balisage créé en 2004, de nombreux add-on développant les possibilités de ce langage existent. L'objectif de ce guide est de tendre vers l’exhaustivité des possibilités de ce langage de formatage dans le cadre de la documentation de YunoHost et non des langages Markdown en général.
|
||||
|
||||
Markdown permet de formater du texte à l'aide de balises, il permet une lecture *humaine* du texte ; même avec le formatage. Même si un unique bloc note est nécessaire il existe de nombreux logiciels markdowns (Markdown sur [framalibre.org](https://framalibre.org/recherche-par-crit-res?keys=markdown)). Sa prise en main est relativement facile.
|
||||
|
||||
## Les différents niveaux de titres
|
||||
|
||||
En rédigeant des titres comme suit :
|
||||
```markdown
|
||||
# Titre de niveau 1
|
||||
## Titre de niveau 2
|
||||
### Titre de niveau 3
|
||||
#### Titre de niveau 4
|
||||
##### Titre de niveau 5
|
||||
###### Titre de niveau 6
|
||||
```
|
||||
|
||||
Ils apparaissent comme cela :
|
||||
# Titre de niveau 1
|
||||
## Titre de niveau 2
|
||||
### Titre de niveau 3
|
||||
#### Titre de niveau 4
|
||||
##### Titre de niveau 5
|
||||
###### Titre de niveau 6
|
||||
|
||||
## Formatage dans les paragraphes
|
||||
|
||||
Pour taper un retour à la ligne sans créer de nouveau paragraphe, il est nécessaire de taper **deux espaces consécutifs**.Sans cela, le texte continuera à la suite en respectant les contraintes générales du style de la page.
|
||||
|
||||
En rédigeant ça :
|
||||
|
||||
```markdown
|
||||
Pour du texte en *italique il faut encadrer par un astérisque* `*`
|
||||
Pour rédiger du **texte en gras par deux astérisques** `**`
|
||||
On peut aussi ~~barrer le texte~~ en encadrant avec deux tildes `~`
|
||||
```
|
||||
|
||||
On peut lire ça :
|
||||
|
||||
Pour du texte en *italique il faut encadrer par un astérisque* `*`
|
||||
Pour rédiger du **texte en gras par deux astérisques** `**`
|
||||
On peut aussi ~~barrer le texte~~ en encadrant avec deux tildes `~`
|
||||
|
||||
## Créer des liens
|
||||
|
||||
Pour créer un lien vers un site hors de la documentation de YunoHost :
|
||||
|
||||
```markdown
|
||||
[Texte à afficher](https://lelien.tld)
|
||||
```
|
||||
|
||||
s'affichera comme tel :
|
||||
[Texte à afficher](https://lelien.tld)
|
||||
|
||||
C'est identique pour les pages de la documentation, excepté que le lien est interne. Il renvoie au fichier du wiki, sans extension de langue et de fichier (le `_fr.md`) :
|
||||
```markdown
|
||||
[Page du wiki](/write_documentation)
|
||||
```
|
||||
|
||||
Le lien renverra vers la page avec la bonne configuration de langue si la page existe.
|
||||
[Page du wiki](/write_documentation)
|
||||
|
||||
### Créer des ancres
|
||||
Une ancre permet de faire un lien vers un point précis dans une page, c'est comme ça que fonctionnent les index en haut de page. Pour créer une ancre, il faut insérer du code à l'endroit de l'ancre sous la forme suivante :
|
||||
|
||||
```markdown
|
||||
Du texte qui sera ne sait même pas qu'il a une ancre <a name="nomancre"></a>
|
||||
```
|
||||
|
||||
Ce qui s'affiche :
|
||||
Du texte qui sera ne sait même pas qu'il a une ancre <a name="nomancre"></a>
|
||||
|
||||
Il est aussi possible de directement renvoyer une ancre au titre, en notant le lien en minuscule avec des `-` à la place des espaces.
|
||||
Il ne reste plus qu'à désigner l'ancre au texte que l'on souhaite rendre interactif :
|
||||
|
||||
```markdown
|
||||
[Mon ancre qui renvoie vers les listes](#nomdelancre)
|
||||
[Mon ancre qui renvoie vers le titre des tableaux](#les-tableaux)
|
||||
```
|
||||
|
||||
[Mon ancre qui renvoie vers les listes](#nomdelancre)
|
||||
[Mon ancre qui renvoie vers le titre des tableaux](#les-tableaux)
|
||||
|
||||
## Afficher des images
|
||||
|
||||
Pour afficher des images, le principe est identique aux liens, excepté l'ajout d'un `!` avant le texte à afficher qui est ici considéré comme le texte à afficher en cas d'impossibilité de chargement de l'image. Une description de l'image convient.
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
Il est possible de faire un lien avec une image, exemple :
|
||||
```markdown
|
||||
[](/write_documentation)
|
||||
```
|
||||
[](/write_documentation)
|
||||
|
||||
L'encart de *texte à afficher en cas d'impossibilité de chargement de l'image* entre les corchets dans le lien de l'image n'est pas obligatoire mais fortement recommandé.
|
||||
|
||||
## Formater une citation
|
||||
|
||||
Les citations permettent de mettre en valeur un propos tenu par une autre personne, le wiki gère lui même la façon dont c'est valorisé. Markdown utilise un chevron fermant, ce symbole : `>`, pour annoncer une citation. Il suffit de les rajouter avant la citation, comme tel :
|
||||
|
||||
```markdown
|
||||
>Du texte de citation du premier niveau
|
||||
>qui peut être formaté en différentes lignes
|
||||
|
||||
>> Et une seconde citation
|
||||
>> avec des doubles chevrons
|
||||
```
|
||||
S'affichera :
|
||||
|
||||
>Du texte de citation du premier niveau
|
||||
>qui peut être formaté en différentes lignes
|
||||
|
||||
>> Et une seconde citation
|
||||
>> avec des doubles chevrons
|
||||
|
||||
## Les listes
|
||||
|
||||
Les listes permettent d'afficher une suite de textes dans une présentation facile, c'est ainsi que sont rédiger les index tels que celui de la page de la [documentation contributeur](/contributordoc).
|
||||
|
||||
### Listes ordonnées
|
||||
|
||||
Les listes ordonnées peuvent s'incrémenter autant que vous le désirez, il n'est pas obligé de donner la bonne correspondance au nombre. Il est possible de noter avec des `1.` et installer trois espaces pour marquer l'incrémentation. Pour une meilleure compréhension du texte brut, il peut être bien d'utiliser les chiffres de manières croissantes pour marquer l'incrémentation, mais c'est bien les trois `espaces` conséquents avant la sous-liste qui désigneront l'incrémentation.
|
||||
|
||||
```markdown
|
||||
1. Liste 1
|
||||
1. Liste 2
|
||||
1. liste 3
|
||||
1. Liste 3a
|
||||
1. Liste 3b
|
||||
1. Liste 3b1
|
||||
1. Liste 3b2
|
||||
1. Liste 3b3
|
||||
1. Liste 1
|
||||
1. Liste 2
|
||||
1. liste 3
|
||||
1. Liste 4
|
||||
1. Liste 5
|
||||
1. liste 6
|
||||
```
|
||||
|
||||
On obtient :
|
||||
|
||||
1. Liste 1
|
||||
1. Liste 2
|
||||
1. liste 3
|
||||
1. Liste 3a
|
||||
1. Liste 3b
|
||||
1. Liste 3b1
|
||||
1. Liste 3b2
|
||||
1. Liste 3b3
|
||||
1. Liste 1
|
||||
1. Liste 2
|
||||
1. liste 3
|
||||
5. Liste 4
|
||||
3. Liste 5
|
||||
4. liste 6
|
||||
|
||||
### Listes non ordonnées<a name="nomdelancre"></a>
|
||||
|
||||
Pour créer une liste non ordonnée, il faut utiliser les symboles `*`, `+` ou `*`. Cela ne changera pas l'apparence du marqueur dans la restitution du texte. C'est l'incrémentation de la liste qui définira le visuel. Pour une meilleure lecture du texte brut, il peut être bien d'utiliser les différents symboles pour marquer l'incrémentation, mais c'est bien les trois espaces avant la sous-liste qui désigneront l'incrémentation.
|
||||
Comme tel :
|
||||
```markdown
|
||||
+ Liste 1
|
||||
+ Liste 2
|
||||
+ liste 3
|
||||
- Liste 3a
|
||||
- Liste 3b
|
||||
* Liste 3b1
|
||||
* Liste 3b2
|
||||
* Liste 3b3
|
||||
+ Liste 1
|
||||
+ Liste 2
|
||||
+ liste 3
|
||||
- Liste 4
|
||||
* Liste 5
|
||||
+ liste 6
|
||||
```
|
||||
|
||||
Ce qui affichera :
|
||||
+ Liste 1
|
||||
+ Liste 2
|
||||
+ liste 3
|
||||
- Liste 3a
|
||||
- Liste 3b
|
||||
* Liste 3b1
|
||||
* Liste 3b2
|
||||
* Liste 3b3
|
||||
+ Liste 1
|
||||
+ Liste 2
|
||||
+ liste 3
|
||||
- Liste 4
|
||||
* Liste 5
|
||||
+ liste 6
|
||||
|
||||
## Les tableaux
|
||||
|
||||
Pour créer un tableau, il faut utiliser la barre verticale `|` et les tirets `-`. Il est obligatoire d'ajouter une ligne de tiret sous la première ligne du tableau. Il n'y a aucune contrainte dans la taille de ce dernier. Il est possible de formater le tableau avec les `:` dans la seconde ligne du tableau, trois options s'offrent à vous :
|
||||
|
||||
| Colonne alignée à gauche | Colonne centrée | Colonne alignée à droite |
|
||||
|:-------------------------|:---------------:|-------------------------:|
|
||||
|`:-----` | `:----:` | `-----:` |
|
||||
|
||||
```markdown
|
||||
| **Un tableau** | Une colonne | Une seconde | Autant que l'on veut |
|
||||
|:--------------:|:-----------:|:-----------:|:--------------------:|
|
||||
| Une ligne formatée | | Et du **texte en gras** | Ou en *italique* |
|
||||
| D'autres lignes | | | [Ou un lien](/contributordoc) |
|
||||
```
|
||||
Ce qui afficherait ça :
|
||||
|
||||
| **Un tableau** | Une colonne | Une seconde | Autant que l'on veut |
|
||||
|:--------------:|:-----------:|:-----------:|:--------------------:|
|
||||
| Une ligne formatée | | Et du **texte en gras** | Ou en *italique* |
|
||||
| D'autres lignes | | | [Ou un lien](/contributordoc) |
|
||||
|
||||
## Bloc de codes
|
||||
|
||||
Pour afficher du texte en brut, des `blocs de codes` peuvent être créer en utilisant l'accent grave `Alt Gr + è` :
|
||||
|
||||
```markdown
|
||||
Soit inline, par exemple pour mettre en valeur une touche comme `Ctrl`
|
||||
```
|
||||
|
||||
ou directement en bloc.
|
||||
La seule différence est dans la quantité d'accents graves :
|
||||
Minimum trois accents graves en ouverture et fermeture de bloc et deux accent grave qui encadre le morceau de texte à formater dans une ligne
|
||||
|
||||
Ce qui donnera au rendu :
|
||||
|
||||
Soit inline, par exemple pour mettre en valeur une touche comme `Ctrl`
|
||||
'''
|
||||
```markdown
|
||||
ou directement en bloc.
|
||||
La seule différence est dans la quantité d'accents graves :
|
||||
Minimum trois accents graves en ouverture et fermeture de bloc et deux accent grave qui encadre le morceau de texte à formater dans une ligne
|
||||
```
|
||||
'''
|
||||
## Liens utiles
|
||||
|
||||
+ La documentation du langage originel Markdown : [daringfireball.net/projects/markdown (en)](https://daringfireball.net/projects/markdown/)
|
||||
+ Tutoriel Markdown sur [markdowntutorial.com](https://markdowntutorial.com)
|
||||
|
||||
## Aller plus loin
|
||||
|
||||
De manière plus général, pour comprendre comment est formaté un texte il suffit juste d'inspecter le document source avec une application note. Ce n'est pas pour autant que le wiki de YunoHost pourra l'exploiter. Il existe bien d'autres possibilités d'utiliser la syntaxe markdown, n'hésitez pas à ajouter des fonctionnalités manquantes. Si vous avez observé des manques et/ou que vous avez des questions, contactez-nous sur [le forum](https://forum.yunohost.org) ou par message directe sur le salon IRC : **#yunohost** sur [irc.freenode.net](https://irc.freenode.net).
|
||||
42
doc_use_git.md
Normal file
42
doc_use_git.md
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
# Propel a contribution with GitHub
|
||||
|
||||
It is of course possible to contribute directly to the YunoHost documentation, but this is not the most convenient way to do so for both the contributor and the person who will inject your contribution into the documentation. Here is a tutorial to understand and create a contribution to the Yunohost documentation using [Git](https://git-scm.com/) and [github.com](http://github.com/) which is the Git forge service that hosts and stores the YunoHost source code and documentation.
|
||||
|
||||
## Create an account on github.com
|
||||
To be able to send your contributions via GitHub, you need to have an account on GitHub, to create the account you will need a valid email address that you have access to. GitHub is a powerful tool with many features, the interface can be a little scary at first.
|
||||
You don't have to give your first and last names, you can use a nickname (when you register `Username`).
|
||||
|
||||
## Fork the YunoHost documentation in your personal repository
|
||||
To fork the source code allows you to create a new branch of development of a software source code or in this case the source code of the documentation. By creating a new branch, this allows you to modify the code and add your contributions without altering the code of the `master` branch, which is the public release of the documentation. This allows you not to have to write down everything at once, but to do it in several steps. (Especially for contributions that require more time).
|
||||
|
||||
Forking a project on GitHub is extremely simple, just click on the Fork button, this will create a new repository on your GitHub account.
|
||||
|
||||
In the title of the new repository, you will see where the repository comes from, in this case `YunoHost/doc`.
|
||||
|
||||
|
||||
> **Point of vigilance !**
|
||||
> If you forge the repository of another contributor than yunohost, you'll get the same files. Except that when you send your changes, they will be sent to the contributor and not to the yunohost repository. The advantage is that it allows you to develop another branch created by the contributor and work with another person on an improvement before submitting it to the main repository.
|
||||
> It is not possible to have a fork from a contributor's repository and the original repository fork at the same time in your own account.
|
||||
|
||||
## Modify and add your contribution
|
||||
Once the repository is forked (copied), you will need to create a new development branch within your repository. It is through this branch that you will modify the files and thus propose improvements to the documentation. The fact that it is a new branch will allow you to make a Pull Request, i.e. a request to add your contributions to the `master` branch, which is the main documentation branch. The development rules on GitHub change depending on the developers of each repository, some have a testing branch in which to offer contributions.
|
||||
More information on what a branch on git-scm.com is: [Branching with Git - What a branch is](https://git-scm.com/book/fr/v1/Les-branches-avec-Git-Ce-qu-est-une-branche).
|
||||
|
||||
## Send your contribution by a Pull Request
|
||||
Create a Pull Request when you want to share your work with the other contributors and integrate it into the master repository (YunoHost's main repository). When publishing a Pull Request, commonly called PR, contributors will be able to amend, comment, add, correct your contribution before it is fully integrated into the repository.
|
||||
|
||||
## Track your contribution and take into account feedback from contributors
|
||||
When you've already create a Pull Request (PR), changes to your development branch in the Git repository will automatically be added to the PR. This doesn't require any additional action. You can also include proposed changes from contributors, who, when they audit the code, may find errors or new, better wording.
|
||||
|
||||
## Bringing up mistakes and wishes through issues
|
||||
YunoHost has a specific Git repository to collect issues: [github.com/YunoHost/issues](https://github.com/YunoHost/issues)
|
||||
An issue, also called a ticket, is an identified problem or a development wish; in this case for documentation, but it is valid for any software repository. Within the framework of the YunoHost documentation it will be mainly proposed issues for the development of the documentation, the identified problems being easily correctable.
|
||||
|
||||
## Going further with Git and working on his workstation
|
||||
Using the power of Git to work on your personal computer means you don't have to create a `commit` each time you save modified documentation pages. It also allows you to use tools and software that make it easier to distinguish between tags used in a documentation page.
|
||||
|
||||
- Online resource: [docs.microsoft.com - Setting up a Git repository locally for documentation](https://docs.microsoft.com/fr-fr/contribute/get-started-setup-local)
|
||||
|
||||
## Some resources elsewhere on the net to go further
|
||||
- [Managing your code with Git and GitHub - openclassrooms.com](https://openclassrooms.com/fr/courses/2342361-gerez-votre-code-avec-git-et-github)
|
||||
- [Git User Interface - git-scm.com](https://git-scm.com/download/gui/linux)
|
||||
43
doc_use_git_fr.md
Normal file
43
doc_use_git_fr.md
Normal file
|
|
@ -0,0 +1,43 @@
|
|||
# Propulser une contribution avec Git
|
||||
|
||||
Il est bien sûr possible de contribuer directement sur la documentation de YunoHost, mais ce n'est pas la manière la plus pratique de le faire tant pour le/la contributeur·trice que pour la personne qui va injecter votre contribution dans la documentation. Voici un tutoriel pour comprendre et créer une contribution à la documentation de Yunohost en utilisant l'outil [Git (en)](https://git-scm.com/) et [github.com](http://github.com/) qui est le service de forge Git qui héberge et stocke le code source de YunoHost ainsi que sa documentation.
|
||||
|
||||
## Création d'un compte sur github.com
|
||||
Pour pouvoir envoyer vos contributions via GitHub, il est nécessaire avoir un compte sur GitHub, pour créer le compte vous aurez besoin d'une adresse e-mail valide à laquelle vous avez accès. GitHub est un outil puissant qui propose de nombreuses fonctionnalités, l'interface peut être un peu effrayant au début.
|
||||
Vous n'êtes pas obligé·ée de donner vos noms et prénoms, vous pouvez utiliser un pseudonyme (lors de l'inscription `Username`).
|
||||
|
||||
|
||||
## Forker la documentation de YunoHost dans votre dépôt personel
|
||||
Forker le code source permet de créer une nouvelle branche de développement d'un code source de logiciel ou dans le cas présent, le code source de la documentation. En créant une nouvelle branche, cela vous permet de modifier le code et d'ajouter vos contributions sans altérer le code de la branche `master` qui est le rendu public de la documentation. Ce qui vous permet de ne pas devoir tout marquer mais le faire en plusieurs étapes. (Notamment pour les contributions demandant plus de temps de travail).
|
||||
|
||||
Forker un projet sur GitHub est extrêmement simple, il suffit ce cliquer sur le bouton Fork, cela créera un nouveau dépôt sur votre espace de GitHub.
|
||||
|
||||
Dans le titre du nouveau dépôt, vous verrez de quelle provenance vient le dépôt, dans le cas présent `YunoHost/doc`
|
||||
|
||||
|
||||
> **Point de vigilance !**
|
||||
> Si vous forkez le dépôt d'un autre contributeur que yunohost, vous aurez les mêmes fichiers. Sauf que quand vous enverrez vos modifications, elles seront envoyées au contributeur et non au dépôt yunohost. L'avantage est que ça vous permet de développer une autre branche créee par le contributeur et ainsi travailler avec une autre personne à une amélioration avant proposition au dépôt principal.
|
||||
> Il n'est pas possible d'avoir un fork du dépot d'un contributeur et le fork dépôt d'origine au même moment dans votre propre dépôt.
|
||||
|
||||
## Modifier et ajouter votre contribution
|
||||
Une fois le dépôt forker (copié), il faudra créer une nouvelle branche de développement au sein de votre dépôt. C'est à travers cette branche que vous allez modifier les fichiers et ainsi proposer des améliorations de la documentation. Le fait que ce soit une nouvelle branche vous permettra par la suite de faire une Pull Request, c'est à dire une demande d'ajout de vos contributions au sein de la branche `master` qui est la branche principale de la documentation. Les règles de développement sur GitHub change selon les développeurs de chaque dépôt, certains ont une branche testing dans laquelle il faut proposer les contributions.
|
||||
Plus d'informations sur qu'est une branche sur git-scm.com : [Les branches avec Git - Ce qu'est une branche](https://git-scm.com/book/fr/v1/Les-branches-avec-Git-Ce-qu-est-une-branche).
|
||||
|
||||
## Envoyer votre contribution par une Pull Request
|
||||
Faire une Pull Request correspond au moment ou vous souahitez partager votre travaille avec le reste des contributeurs⋅trices et l'intégrer au dépot master (dépôt principale de Yunohost). Lors de la publication d'un Pull Request, couramment nommé PR, les contributeurs⋅trices pourront amender, commenter, ajouter, corriger votre contribution avant intégration complète au dépot.
|
||||
|
||||
## Suivre votre contribution et prendre en compte les retours des contributeurs·trices
|
||||
Lorsque vous avez déjà fait une PR (Pull Request), les modifications de votre branche de développement sur le dépôt Git se rajouteront automatiquement à la PR. Cela ne nécessite aucune action supplémentaire. Vous pouvez aussi intégrer les propositions de modifications de contributeurs, qui lorsqu'ils/elles auditeront le code, peuvent trouver des erreurs ou de nouvelles formulations plus adaptées.
|
||||
|
||||
## Faire remonter des erreurs et des souhaits par des issues
|
||||
YunoHost dispose d'un dépôt Git spécifique pour le recueil des issues : [github.com/YunoHost/issues](https://github.com/YunoHost/issues)
|
||||
Une issue aussi appelé ticket, est un problème identifié ou alors un souhait de développement ; dans le cas présent pour la documentation, mais c'est valable pour tout dépôt logiciel. Dans le cadre de la documentation de YunoHost il sera surtout proposé des issues pour le développement de la documentation, les problèmes identifiés étant facilement corrigeable.
|
||||
|
||||
## Aller plus loin avec Git et travailler sur son poste de travail
|
||||
Utiliser la puissance de Git et ainsi travailler sur son ordinateur personnel, permet entre autres de ne pas avoir à créer de `commit` à chaque enregistrement intermédiaire des pages de documentations modifiées. Cela permet aussi d'utiliser des outils et logiciels qui permettent une distinction plus facile des codes utilisés dans une page de documentation.
|
||||
|
||||
- Ressource en ligne : [docs.microsoft.com - Configurer un référentiel Git localement pour la documentation](https://docs.microsoft.com/fr-fr/contribute/get-started-setup-local)
|
||||
|
||||
## Quelques ressources ailleurs sur le net pour aller plus loin
|
||||
- [Gérer son code avec Git et GitHub - openclassrooms.com](https://openclassrooms.com/fr/courses/2342361-gerez-votre-code-avec-git-et-github)
|
||||
- [Interface utilisateurs·trices de Git - git-scm.com](https://git-scm.com/download/gui/linux)
|
||||
36
doc_writing_guide.md
Normal file
36
doc_writing_guide.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
# Guide to writing application documentation
|
||||
|
||||
## User documentation pages / administrateurs⋅trices
|
||||
|
||||
Add a one-click install button (such as https://yunohost.org/#/app_piwigo_fr) and a button on the application integration level.
|
||||
|
||||
Classification of available applications by tags (genre, Git, association management, e-mails, etc).
|
||||
|
||||
## Some typical and general uses (writing framework)
|
||||
|
||||
+ When a link points to a page that is not in the language of the original page, it is customary to add `(en)` (for a link that points to a page in English).
|
||||
+ rename the images in the following order:`description_application.ext`.
|
||||
|
||||
### General frame application documentation
|
||||
|
||||
1. Logo (dimension 80 pixels high) + level 1 title.
|
||||
1. One-click install button, Integration level for each type of processor.
|
||||
1. An index at the top of the documentation with cross-references to all the chapters of the documentation.
|
||||
1. A general presentation of the application and its function.
|
||||
2. A configuration part of the application.
|
||||
1. An administration part of the application.
|
||||
1. A part on limitations related to YunoHost.
|
||||
1. A part on desktop clients (if any). A link to different third-party applications if there are several (possible link to the applications catalgue [framalibre.org](https://framalibre.org)) or a link to the page about desktop applications if official applications are provided.
|
||||
1. A part with:
|
||||
- the link to the official site
|
||||
- the link to the documentation
|
||||
- Links to the YunoHost package and issues
|
||||
|
||||
Screen for writing documentation pages: [here](/app_writing_guide)
|
||||
|
||||
## Roadmap
|
||||
|
||||
1. Document applications.
|
||||
1. Document applications at work (marked: work) level 8/7/6.
|
||||
1. Translate the documentation page at least into French and English.
|
||||
1. Do a PR on the application repository
|
||||
36
doc_writing_guide_fr.md
Normal file
36
doc_writing_guide_fr.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
# Guide de rédaction de la documentation des applications
|
||||
|
||||
## Pages de documentations utilisateurs.trices / administrateurs⋅trices
|
||||
|
||||
Ajouter un bouton installer en un clique (comme par exemple : https://yunohost.org/#/app_piwigo_fr) et un bouton sur le niveau d'intégration de l'application.
|
||||
|
||||
Classement des applications disponibles par tags (genre, Git, gestion associations, courriels, etc).
|
||||
|
||||
## Quelques usages types et d'ordres général (trame de rédaction)
|
||||
|
||||
+ Lorsqu'un lien renvoi vers une page qui n'est pas dans la langue de la page d'origine, il est d'usage d'ajouter `(en)`(Pour un lien qui pointe vers une page en anglais).
|
||||
+ renommer les images dans l'ordre suivant :`nomapplication_descriptif.ext`
|
||||
|
||||
### Trame général documentation applications
|
||||
|
||||
1. Logo (dimension 80 pixels de hauteurs) + titre de niveau 1.
|
||||
1. Bouton installer en un clique, Niveau d'intégration pour chaque type de processeur.
|
||||
1. Un index en tête de documentations avec renvois vers l'ensemble des chapitres de la documentation.
|
||||
1. Une présentation général de l'application et de sa fonction.
|
||||
2. UNe partie configuration de l'application.
|
||||
1. Une partie administration de l'application.
|
||||
1. Une partie sur les limitation liés à YunoHost.
|
||||
1. Une partie sur les client desktop (si il en existe). Lien vers différentes applications tierces si il en existe plusieurs (lien possible avec le catalgue d'applications [framalibre.org](https://framalibre.org)) ou un lien vers la page concernant les applications desktop si des applications officiels sont fournis.
|
||||
1. Une partie avec :
|
||||
- le lien vers le site officiel
|
||||
- le lien vers la documentation
|
||||
- Les liens vers le package de YunoHost et issues
|
||||
|
||||
Trame pour la rédaction des pages de documentations : [ici](/app_writing_guide)
|
||||
|
||||
## Feuille de route
|
||||
|
||||
1. Documenter les applications.
|
||||
1. Documenter les applications au travail (marqué : work) niveau 8/7/6.
|
||||
1. Traduire la page de documentation à minima en français et en anglais.
|
||||
1. Faire une PR sur le dépôt de l'application concerné vers la page de documentation.
|
||||
BIN
images/pihole_logo.png
Normal file
BIN
images/pihole_logo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.7 KiB |
Loading…
Add table
Reference in a new issue