Cette description est juste pour l’édition de la documentation en anglais. Toutes les nouvelles informations doivent être ajoutées d’abord en Anglais. Si vous voulez traduire la documentation dans d’autres langues (merci), utilisez crowdin.
Pour savoir comment formater le texte (titre, gras …) et définir les liens, reportez-vous à la section « Syntaxe de code » de cette page.
Si vous avez des questions, des commentaires ou de nouvelles idées, vous pouvez contacter l’équipe de documentation via discord. Faire un PR n’est pas difficile, mais nous pouvons vous aider à éditer la documentation.
À un moment donné, on vous suggère de faire un PR. PR est l’acronyme de Pull Request, et c’est une façon d’ajouter ou de modifier des informations enregistrées dans GitHub. En fait, ce n’est pas si difficile à faire et c’est une excellente façon de contribuer. Cette documentation est ici parce que les gens comme vous ont fait des PRs. Ne craignez pas de vous tromper ou d’éditer les mauvais documents. There is always a review process before changes are merged into the « formal » AAPS documentation repository. Vous ne pouvez pas endommager les originaux si vous faites des erreurs lors du processus de PR. Le processus général est :
Apportez des modifications au code ou à la documentation en modifiant le contenu existant.
Vérifiez deux fois que vos modifications vous semblent bonnes.
Prenez quelques notes sur ce qui a changé afin que les personnes puissent comprendre les modifications.
Créer un Pull Request, qui demande aux administrateurs d’utiliser vos modifications.
Ils feront une vérification et soit (1) ils fusionneront vos modifications, (2) ils vous feront un retour au sujet de vos modifications, ou (3) ils commenceront un nouveau document avec vos modifications.
(Remarque : Si vous êtes un apprenant visuel, il y a une vidéo YouTube ici montrant le flux de travail PR.)
Pour notre exemple, nous allons faire une modification à AndroidAPSdocs. Cela ne doit PAS être fait dans l’environnement linux de votre plateforme. Cela peut être fait sur n’importe quel PC Windows, Mac, etc. (n’importe quel ordinateur avec un accès à Internet).
Accédez à https://github.com/openaps/AndroidAPSdocs et appuyez sur Fork en haut à droite pour faire votre propre copie du référentiel.
Allez sur n’importe quelle page et accédez à la page que vous souhaitez modifier. Cliquez sur la boîte noire en bas à gauche de la page avec le mot vert « v: latest » ou similaire. Dans la fenêtre pop up qui apparaît, cliquez sur le mot « edit » pour éditer dans GitHub.
Or you can click on the « Edit in GitHub » link in the upper right corner, and then click the pencil icon that appears in the top bar of the page contents to be edited.
L’une ou l’autre des options de l’étape 2 créera une nouvelle branche dans VOTRE repository Github où vos modifications seront enregistrées. Effectuez vos modifications dans le fichier.
We are using markdown for the docs pages. The file have got the suffix « .md ».The Markdown specification is not fixed and we use at the moment the myst_parser for our markdown files. Take care to use the correct syntax as described below.
Vous avez travaillé dans l’onglet « <>Edit file ». Sélectionnez l’onglet « Preview changes » pour afficher une prévisualisation de votre page et vérifier que tous vos changements sont comme vous le vouliez. Si vous voyez que c’est perfectible, revenez à l’onglet d’édition pour faire vos améliorations.
Une fois vos modifications terminées, faites défiler jusqu’au bas de la page. Dans la zone du bas, indiquez vos commentaires dans le champ texte qui indique « Add an optional extended description… ». Le titre par défaut est le nom de fichier. Essayez d’inclure une phrase expliquant la raison du la modification. Indiquer la raison permet d’aider les valideurs à comprendre ce que vous essayez de faire avec le PR.
Cliquez sur le bouton vert « Propose file changes » ou « Commit changes ». Dans la page qui s’affiche, cliquez sur « Create Pull Request » et de nouveau dans la page suivante, cliquez sur « Create Pull Request ».
Cela termine l’ouverture d’un Pull Request, PR. GitHub affecte au PR un numéro, situé après le titre et un caratère dièse. Retournez sur cette page pour vérifier si vous avez un retour (ou si vous avez des notifications GitHub envoyées par email, vous recevrez des emails vous indiquant toutes activités sur le PR). The edit will now be in a list of PR’s that the team will review and potentially give feedback on before committing to the main documentation for AAPS! Si vous voulez vérifier l’avancement du PR, vous pouvez cliquer sur le logo de la cloche dans le coin supérieur droit de votre compte GitHub pour voir toutes vos notifications.
PS: Your fork and branch will still be sitting on your own personal GitHub account. After you get a notification that your PR has been merged, you can delete your branch if you are done with it (Step 8’s notification area will provide a link to delete the branch once it has been closed or merged). For future edits, if you follow this procedure the edits will always start with an updated version of the AndroidAPSdocs repositories. If you choose to use another method to start a PR request (e.g., editing starting from your forked repo’s master branch as the starting point), you will need to ensure your repo is up-to-date by performing a « compare » first and merging in any updates that have happened since you last updated your fork. Since people tend to forget to update their repos, we recommend using the PR process outlined above until you get familiar with performing « compares ».
We are using markdown for the docs pages. The files have got the suffix « .md ».
Markdown is a very simple text formating language which separates text content from text formating.
The writer only e.g. marks a headline as level 1 headline and the markdown processor generate during processing the necessary HTML code to render the heading in HTML.
The idea behind this is that
the writer should think about the text and not the formating first,
the markdown text is open for exchange between different markdown tools instead of e.g. proprietray tools like Mircosoft Windows and
you can generate several output formats from one markdown file.
Markdown is not a 100% fixed standard and we try to stay as near as possible to the standard to
stay flexible to change markdown tools as needed or forced in the further innovation of markdown tools and markdown SaaS services and
enable us to use a transaltion services to translate the english language in a target language like French or German because they can work on markdown but not complex formating codes because they can’t separate there content from layout which might be fatal.
You can insert lists in lists by indenting the next level with 4 more spaces to the right than the one before.
1. premier
2. deuxième
3. third
1. one element
2. another element
3. and another element
4. quatre
5. cinq
6. six :::
7. premier
8. deuxième
9. third
1. one element
2. another element
3. and another element
10. quatre
11. cinq
12. six
### Images
To include images you use this markdown syntax.
* images: ``
The type of image should be PNG or JPEG.
Images names should confirm to one of following naming rules. In the example I use png as suffix. In case you use JPEG please replace it with jpeg.
* `filename-image-xx.png` where xx is a unique double digit number for the images in this file.
* `filename-image-xx.png` where xx is a meaning full name for the author of the md file.
Images are located in the images folder for the english language and propagated to the other languages automatically by Crowdin. You have nothing to do for this!
We are not translating images at the moment.
(make-a-PR-image-size)= Use a reasonable size for the images which must be readable on PC, tablet and mobiles.
* Screenshots from web pages images should be up to **1050 pixels wide**.
* Diagramms of process flows should be up to **1050 pixels wide**.
* Screenshots from the app should be up to **300 to 400 pixels wide**.
### Links
#### External links
External links are links to external web sites.
* external link: `[alt text](www.url.tld)`
#### Internal links to the start of a md file
Internal links to pages are links to the start of a md file which is hosted on our own server.
* internal link to .md page: `[alt text](../folder/file.md)`
#### Internal links to named inline refernces
Internal links to named inline refernces are links to any point in a md file which is hosted on our own server and where a reference was set to link to.
Add a named reference at the location in the target md file you want to jump to.
`(name-of-my-md-file-this-is-my-fancy-named-reference)=`
The named reference must be unique in the whole AndroidAPSDocs md files and not only the own md file it resides in!
Therefore it is a good practice to start with the filename and then the reference name you select.
Use only lowercase letters and hyphenate words.
Then link this refernce in the text you are writing with the following kind of link.
* Internal links to named inline refernces: `[alt text](name-of-my-md-file-this-is-my-fancy-named-reference)`
### Notes, Warnings, Collapsing Notes
You can add notes and warning boxes to documentation.
Furthermore you can add collapsing notes for detailed information which would users who are not interested in the details quench to read the text at all. Please use these carefully as the documentation should be as easy to read as possible.
#### Notes
:::: :::{admonition} Note :class: note
This is a note. ::: ::::
:::{admonition} Note :class: note
This is a note. :::
#### Warnings
:::: :::{admonition} Warning :class: warning
This is a warning. ::: ::::
:::{admonition} Warning :class: warning
This is a warning. :::
#### Collapsing Notes
:::: :::{admonition} further detailed readings for interested readers :class: dropdown
This admonition has been collapsed, meaning you can add longer form content here, without it taking up too much space on the page. ::: ::::
:::{admonition} further detailed readings for interested readers :class: dropdown
This admonition has been collapsed, meaning you can add longer form content here, without it taking up too much space on the page. :::
Comment éditer la documentation
Cette description est juste pour l’édition de la documentation en anglais. Toutes les nouvelles informations doivent être ajoutées d’abord en Anglais. Si vous voulez traduire la documentation dans d’autres langues (merci), utilisez crowdin.
Pour savoir comment formater le texte (titre, gras …) et définir les liens, reportez-vous à la section « Syntaxe de code » de cette page.
Généralités
Si vous avez des questions, des commentaires ou de nouvelles idées, vous pouvez contacter l’équipe de documentation via discord. Faire un PR n’est pas difficile, mais nous pouvons vous aider à éditer la documentation.
À un moment donné, on vous suggère de faire un PR. PR est l’acronyme de Pull Request, et c’est une façon d’ajouter ou de modifier des informations enregistrées dans GitHub. En fait, ce n’est pas si difficile à faire et c’est une excellente façon de contribuer. Cette documentation est ici parce que les gens comme vous ont fait des PRs. Ne craignez pas de vous tromper ou d’éditer les mauvais documents. There is always a review process before changes are merged into the « formal » AAPS documentation repository. Vous ne pouvez pas endommager les originaux si vous faites des erreurs lors du processus de PR. Le processus général est :
Apportez des modifications au code ou à la documentation en modifiant le contenu existant.
Vérifiez deux fois que vos modifications vous semblent bonnes.
Prenez quelques notes sur ce qui a changé afin que les personnes puissent comprendre les modifications.
Créer un Pull Request, qui demande aux administrateurs d’utiliser vos modifications.
Ils feront une vérification et soit (1) ils fusionneront vos modifications, (2) ils vous feront un retour au sujet de vos modifications, ou (3) ils commenceront un nouveau document avec vos modifications.
(Remarque : Si vous êtes un apprenant visuel, il y a une vidéo YouTube ici montrant le flux de travail PR.)
Pour notre exemple, nous allons faire une modification à AndroidAPSdocs. Cela ne doit PAS être fait dans l’environnement linux de votre plateforme. Cela peut être fait sur n’importe quel PC Windows, Mac, etc. (n’importe quel ordinateur avec un accès à Internet).
Accédez à https://github.com/openaps/AndroidAPSdocs et appuyez sur Fork en haut à droite pour faire votre propre copie du référentiel.
Allez sur n’importe quelle page et accédez à la page que vous souhaitez modifier. Cliquez sur la boîte noire en bas à gauche de la page avec le mot vert « v: latest » ou similaire. Dans la fenêtre pop up qui apparaît, cliquez sur le mot « edit » pour éditer dans GitHub.
Or you can click on the « Edit in GitHub » link in the upper right corner, and then click the pencil icon that appears in the top bar of the page contents to be edited.
L’une ou l’autre des options de l’étape 2 créera une nouvelle branche dans VOTRE repository Github où vos modifications seront enregistrées. Effectuez vos modifications dans le fichier.
We are using markdown for the docs pages. The file have got the suffix « .md ».The Markdown specification is not fixed and we use at the moment the myst_parser for our markdown files. Take care to use the correct syntax as described below.
Vous avez travaillé dans l’onglet « <>Edit file ». Sélectionnez l’onglet « Preview changes » pour afficher une prévisualisation de votre page et vérifier que tous vos changements sont comme vous le vouliez. Si vous voyez que c’est perfectible, revenez à l’onglet d’édition pour faire vos améliorations.
Une fois vos modifications terminées, faites défiler jusqu’au bas de la page. Dans la zone du bas, indiquez vos commentaires dans le champ texte qui indique « Add an optional extended description… ». Le titre par défaut est le nom de fichier. Essayez d’inclure une phrase expliquant la raison du la modification. Indiquer la raison permet d’aider les valideurs à comprendre ce que vous essayez de faire avec le PR.
Cliquez sur le bouton vert « Propose file changes » ou « Commit changes ». Dans la page qui s’affiche, cliquez sur « Create Pull Request » et de nouveau dans la page suivante, cliquez sur « Create Pull Request ».
Cela termine l’ouverture d’un Pull Request, PR. GitHub affecte au PR un numéro, situé après le titre et un caratère dièse. Retournez sur cette page pour vérifier si vous avez un retour (ou si vous avez des notifications GitHub envoyées par email, vous recevrez des emails vous indiquant toutes activités sur le PR). The edit will now be in a list of PR’s that the team will review and potentially give feedback on before committing to the main documentation for AAPS! Si vous voulez vérifier l’avancement du PR, vous pouvez cliquer sur le logo de la cloche dans le coin supérieur droit de votre compte GitHub pour voir toutes vos notifications.
PS: Your fork and branch will still be sitting on your own personal GitHub account. After you get a notification that your PR has been merged, you can delete your branch if you are done with it (Step 8’s notification area will provide a link to delete the branch once it has been closed or merged). For future edits, if you follow this procedure the edits will always start with an updated version of the AndroidAPSdocs repositories. If you choose to use another method to start a PR request (e.g., editing starting from your forked repo’s master branch as the starting point), you will need to ensure your repo is up-to-date by performing a « compare » first and merging in any updates that have happened since you last updated your fork. Since people tend to forget to update their repos, we recommend using the PR process outlined above until you get familiar with performing « compares ».
Syntaxe du Code
We are using markdown for the docs pages. The files have got the suffix « .md ».
Markdown is a very simple text formating language which separates text content from text formating.
The writer only e.g. marks a headline as level 1 headline and the markdown processor generate during processing the necessary HTML code to render the heading in HTML.
The idea behind this is that
the writer should think about the text and not the formating first,
the markdown text is open for exchange between different markdown tools instead of e.g. proprietray tools like Mircosoft Windows and
you can generate several output formats from one markdown file.
Markdown is not a 100% fixed standard and we try to stay as near as possible to the standard to
stay flexible to change markdown tools as needed or forced in the further innovation of markdown tools and markdown SaaS services and
enable us to use a transaltion services to translate the english language in a target language like French or German because they can work on markdown but not complex formating codes because they can’t separate there content from layout which might be fatal.
Headlines
Headline 1:
# headlineHeadline 2:
## headlineHeadline 3:
### headlineHeadline 4:
#### headlineWe try to avoid further leveles of headlines.
Text format
bold:
**text**italic:
*text*ordered list
one element
another element
and another element :::
one element
another element
and another element
multi level list
You can insert lists in lists by indenting the next level with 4 more spaces to the right than the one before.
1. premier 2. deuxième 3. third 1. one element 2. another element 3. and another element 4. quatre 5. cinq 6. six ::: 7. premier 8. deuxième 9. third 1. one element 2. another element 3. and another element 10. quatre 11. cinq 12. six ### Images To include images you use this markdown syntax. * images: `` The type of image should be PNG or JPEG. Images names should confirm to one of following naming rules. In the example I use png as suffix. In case you use JPEG please replace it with jpeg. * `filename-image-xx.png` where xx is a unique double digit number for the images in this file. * `filename-image-xx.png` where xx is a meaning full name for the author of the md file. Images are located in the images folder for the english language and propagated to the other languages automatically by Crowdin. You have nothing to do for this! We are not translating images at the moment. (make-a-PR-image-size)= Use a reasonable size for the images which must be readable on PC, tablet and mobiles. * Screenshots from web pages images should be up to **1050 pixels wide**. * Diagramms of process flows should be up to **1050 pixels wide**. * Screenshots from the app should be up to **300 to 400 pixels wide**. ### Links #### External links External links are links to external web sites. * external link: `[alt text](www.url.tld)` #### Internal links to the start of a md file Internal links to pages are links to the start of a md file which is hosted on our own server. * internal link to .md page: `[alt text](../folder/file.md)` #### Internal links to named inline refernces Internal links to named inline refernces are links to any point in a md file which is hosted on our own server and where a reference was set to link to. Add a named reference at the location in the target md file you want to jump to. `(name-of-my-md-file-this-is-my-fancy-named-reference)=` The named reference must be unique in the whole AndroidAPSDocs md files and not only the own md file it resides in! Therefore it is a good practice to start with the filename and then the reference name you select. Use only lowercase letters and hyphenate words. Then link this refernce in the text you are writing with the following kind of link. * Internal links to named inline refernces: `[alt text](name-of-my-md-file-this-is-my-fancy-named-reference)` ### Notes, Warnings, Collapsing Notes You can add notes and warning boxes to documentation. Furthermore you can add collapsing notes for detailed information which would users who are not interested in the details quench to read the text at all. Please use these carefully as the documentation should be as easy to read as possible. #### Notes :::: :::{admonition} Note :class: note This is a note. ::: :::: :::{admonition} Note :class: note This is a note. ::: #### Warnings :::: :::{admonition} Warning :class: warning This is a warning. ::: :::: :::{admonition} Warning :class: warning This is a warning. ::: #### Collapsing Notes :::: :::{admonition} further detailed readings for interested readers :class: dropdown This admonition has been collapsed, meaning you can add longer form content here, without it taking up too much space on the page. ::: :::: :::{admonition} further detailed readings for interested readers :class: dropdown This admonition has been collapsed, meaning you can add longer form content here, without it taking up too much space on the page. :::