Documentation style guide

TODO: Consider reordering content

Ce guide comprend des informations sur le style attendu, la syntaxe spécifique à MkDocs, les différents outils nécessaires et la traduction de la documentation, en ce qui concerne la rédaction d'un nouveau contenu et la traduction d'un contenu existant.

Style général¶

Les titres et les en-têtes ne doivent comporter que le premier mot en majuscule.
Nous préférons l'orthographe américaine, avec quelques libertés pour le langage familier spécifique à la programmation (par exemple, "apps") et le verbe des noms (par exemple, "scrollable").
L'orthographe de "artefact" et "artefacts" est la suivante.
Toute référence à un nom de produit doit utiliser la majuscule préférée du produit. (par exemple, "macOS", "GTK", "pytest", "Pygame", "PyScript").
Si un terme est utilisé "en tant que code", il doit être cité en tant que code en ligne, en l'entourant d'une simple barre oblique, plutôt que d'être ajouté au dictionnaire.

Reference links¶

MkDocs rend les liens standard au format Markdown. Il prend également en charge le rendu d'une syntaxe de lien de référence qui vous permet d'établir un lien vers divers autres éléments de la documentation à l'aide d'un lien Markdown modifié. Cela inclut les liens vers, entre autres, les ancres d'en-tête Markdown standard, les ancres d'en-tête et de texte Markdown personnalisées, les ID de référence personnalisés, les classes documentées et les méthodes ou attributs de classe, ainsi que les références spécifiques à la documentation externe.

Les liens standard formatés en Markdown sont les suivants :

[Link text](https://example.com/)

Vous pouvez également utiliser ce format pour créer un lien vers un fichier local :

[Link text](path/to/file.md)

Le lien vers une ancre dans le même fichier est formaté comme suit :

[Link text](#anchor-name)

Le lien vers une ancre dans un autre fichier est formaté comme suit :

[Link text][anchor-name]

Si vous devez créer un lien vers une ancre dans un autre fichier et que le nom de l'ancre est dupliqué dans plusieurs fichiers, vous pouvez générer une ancre personnalisée pour le contenu visé (comme indiqué dans la section suivante) et créer un lien vers cette ancre à l'aide du formatage de lien de référence :

[Link text][custom-anchor-name]

Il existe plusieurs options pour établir un lien avec une classe documentée, ou une méthode ou un attribut de classe, que vous établissiez un lien à partir du même fichier ou d'un fichier distinct. Lorsque vous créez un lien vers des classes, etc., vous devez inclure des crochets dans la première série de crochets pour que le nom soit considéré comme du code en ligne. Les crochets ne sont nécessaires que si vous utilisez un texte personnalisé qui ne doit pas être rendu sous forme de code en ligne. Les crochets ne doivent jamais être inclus dans la deuxième série de crochets.

L'établissement d'un lien vers une classe tout en affichant l'espace de noms est formaté comme suit :

[`module.ClassName`][]

L'établissement d'un lien vers une classe tout en affichant uniquement le nom de la classe est formaté comme suit :

[`ClassName`][module.ClassName]

Attributes are the same as above, with the attribute name included. The following displays the namespace:

[`module.ClassName.attributename`][]

As with classes, displaying only the attribute name is formatted as follows:

[`attributename`][module.ClassName.attributename]

Methods should be displayed with () after the namespace, and therefore must be handled differently than attributes. The following is the appropriate way to link to a method:

[`module.ClassName.methodname()`][module.ClassName.methodname]

La méthode suivante affiche uniquement le nom de la classe et de la méthode. Il faut également inclure les parenthèses après le nom :

[`Classname.methodname()`][module.Classname.methodname]

You can link to a class, method, or attribute while displaying arbitrary text, using the same method with the applicable namespace. Doing this with a class is formatted as follows:

[link text][module.ClassName]

Il est également possible d'établir un lien direct avec la documentation de base de Python, ainsi qu'avec la documentation de Pillow. Par exemple, un lien vers la documentation de int :

[`int`][]

Lien vers la documentation de Pillow Image :

[`PIL.Image.Image`][]

Ancres Markdown personnalisées¶

Markdown generates anchors for all headers (anything on a single line starting with between one and six # symbols), based on the content of the header. For example, the anchor generated for this section is custom-markdown-anchors. There are situations where it makes sense to instead set a custom anchor, such as, if you are using the anchor in a reference link, or if the header is overly verbose, and you need something more memorable available for reuse.

Reference links and custom anchors

Any header that is referenced in text content via a MkDocs reference link must have a custom anchor attached. Otherwise, there is the potential to break links when header content is translated.

MkDocs reference links are any links formatted as follows:

[Link text][anchor-name]

Therefore, an example related header must be formatted as follows:

# Header { #anchor-name }

The general syntax for setting a custom anchor is as follows:

# Header text { #anchor }

For example, customizing the anchor for this section to custom-anchors would be done with the following formatting:

## Custom Markdown anchors { #custom-anchors }

Vous pouvez également créer une ancre sur le contenu général, y compris le texte et les codeblocks. Le formatage suivant, avec des nouvelles lignes au-dessus et au-dessous, doit être inclus au-dessus du contenu vers lequel vous souhaitez créer un lien :

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

Markdown elements that require specific formatting¶

En raison de la manière dont les fichiers de traduction sont générés, il est important d'inclure les nouvelles lignes requises dans la syntaxe Markdown pour les remontrances, les notes, les tabulations, les directives Jinja, les légendes et l'alignement des images, etc.

Admonitions et notes¶

Les remontrances doivent être formatées comme suit, en veillant notamment à ce qu'une nouvelle ligne précède et suive le début et la fin de la remontrance :

Content above.

/// admonition | Title

Admonition text, including
multi-line text.

A second paragraph.

///

Content below.

Les avertissements sur les notes requièrent le même formatage et les mêmes nouvelles lignes :

Content above.

/// note | Note

Note text here.

///

Content below.

This format also works for danger, tip, and warning admonition types.

Contenu des onglets¶

Le contenu des onglets est formaté comme suit, avec une nouvelle ligne avant le début et après la fin du bloc de contenu :

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

Une tabulation avec un avertissement imbriqué serait formatée comme suit, avec une nouvelle ligne avant et après le bloc de contenu :

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

Directives de Jinja¶

Certaines fonctionnalités de la documentation utilisent des directives Jinja dans le texte. Tout ce qui utilise les directives Jinja doit être entouré de nouvelles lignes. Par exemple, le tutoriel BeeWare contient des conditionnelles Jinja basées sur des variables pour déterminer quel avertissement afficher sur la page principale. Ces conditionnelles sont formatées comme suit :

Content above.

{% if config.extra.translation_type == "original" %}

/// admonition | Admonition title

Text

///

{% endif %}

Content below.

There is also syntax for substituting symbols or text. This syntax is a variable wrapped in a pair of matching double curly braces, and, if on its own line, must include a newline before and after.

Content above.

{{ variable }}

Content below.

Images avec syntaxe de légende¶

Que la syntaxe de légende soit utilisée pour centrer une image ou pour fournir une légende d'image, elle doit inclure des nouvelles lignes entre chaque section.

Par exemple, lorsque vous ajoutez une légende vide pour centrer une image, vous devez la formater comme suit, avec une nouvelle ligne avant et après le bloc de contenu :

Content above.

![Alt text](/path/to/image.png)

/// caption

///

Content below.

L'ajout d'une légende à une image nécessite également une nouvelle ligne avant et après, et se présente comme suit :

Content above.

![Alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

Code block tips¶

Mise en évidence du langage et du code¶

Vous pouvez spécifier la langue du code contenu dans le bloc de code en incluant le nom de la langue après les trois premiers crochets, sans espace entre les deux. Le code est ainsi mis en évidence de manière appropriée lors du rendu du code. Par exemple, pour spécifier Python, vous commencerez le bloc de code par ``python.

Commandes de la console et bouton "copier¶

Si vous incluez des commandes de console, ou des commandes avec sortie, si vous les nommez console ou doscon, selon le système d'exploitation auquel vous faites référence, vous pouvez inclure l'invite, et seule la commande sera copiée lorsque vous cliquerez sur le bouton copier. Par exemple, si vous commencez un bloc de code avec `console, et que vous incluez le contenu suivant :

$ mkdir test
$ ls
test

Ensuite, en cliquant sur le bouton de copie du bloc de code, vous ne copierez que les commandes et ignorerez les invites et la sortie. Cela vous permet d'indiquer qu'il s'agit de commandes de la console, tout en permettant aux utilisateurs d'utiliser efficacement le bouton de copie.

Mise en évidence de lignes de code spécifiques¶

Vous pouvez mettre en évidence des lignes de code spécifiques. Par exemple, pour mettre en évidence la ligne 2, vous devez ajouter un espace après le langage, suivi de {hl_lines="2"}. Ainsi, votre bloc de code commencerait par `python {hl_lines="2"}. Le résultat est le suivant :

import toga
from toga.style.pack import COLUMN, ROW

Vous pouvez mettre en évidence plusieurs lignes différentes. Par exemple, python {hl_lines="3 5 9"} mettrait en évidence les lignes 3, 5 et 9. Vous pouvez également mettre en évidence une plage de lignes. Par exemple, python {hl_lines="3-8"} met en évidence les lignes 3 à 8. Vous pouvez mettre en évidence plusieurs plages avec, par exemple, python {hl_lines="9-18 23-44"}.

Formatage des images¶

La largeur des images peut être définie et celles-ci peuvent être alignées à gauche, à droite et au centre (avec une réserve sur le terme "centre").

La définition de la largeur de 300px sur une image serait formatée comme suit :

![Image alt text](../path/to/image.png){ width="300px" }

L'alignement d'une image à gauche (ou à droite) serait formaté comme suit :

![Image alt text](../path/to/image.png){ align=left }

Il n'est pas possible de centrer une image avec l'attribut align. La solution consiste à faire suivre l'image d'une légende vide, et elle sera centrée. Vous devez inclure des nouvelles lignes entre chaque section, ainsi qu'avant et après. Il est formaté comme suit :

![Image alt text](../path/to/image.png)

/// caption

///

`pyspelling`¶

Nous utilisons le correcteur orthographique pyspelling. Il est exécuté pendant les vérifications lint.

Lorsque pyspelling identifie un mot mal orthographié, dans la plupart des cas, il doit être corrigé dans le contenu de la documentation.

Dans le cas rare où il identifie un mot valide qui n'est pas dans le dictionnaire pyspelling, vous avez deux options :

S'il s'agit d'un mot susceptible d'être réutilisé plusieurs fois, vous devez l'ajouter au document spelling_wordlist dans le répertoire docs, par ordre alphabétique.
S'il s'agit d'un mot qui n'est pas susceptible d'être utilisé à nouveau, vous pouvez le mettre dans une balise <nospell> / </nospell>, et pyspelling l'ignorera en ligne.

Utiliser les snippets pour inclure du contenu externe¶

For details on how to include external content from a local file or a URL, see the Snippets extension documentation. Snippets should be used as long as the document does not contain Jinja directives that need to be executed (the Jinja execution happens alongside the Snippets processing, and therefore any Jinja in the file will not be processed). Snippets is necessary if you want to be able to use delimiters that allow you to include specific parts of a file separately, e.g. the source document is divided up into sections to be injected separately from each other.

Important notes:

Nous utilisons -8<- comme identifiant des Snippets. La documentation présente plusieurs options ; veuillez suivre notre style.
Files found in BeeWare Docs Tools shared content are treated as "local" content, and should be added using only the filename, i.e. this style guide would be included using -8<- "docs_style_guide.md".
If you are including external content from a file on GitHub via a URL, you must use the raw content URL, or it will render the full webpage embedded wherever you include it.

Using Macros to include content from BeeWare Docs Tools shared content¶

You can also include content from the BeeWare Docs tools shared content directory using the Macros MkDocs plugin. This method is necessary if the document contains Jinja directives that need to be executed, and should only be used in this situation. It will not work with external content via a URL. The Macros variable-replacement mechanism works with this method.

There are options for including content using Macros:

Use include. If you want to include the document with no other manual changes to it, you can use the following:
```
{% include "filename.md" %}
```
Use extends. If you have included Jinja in the document that allows you to override specific sections, you will need to include the content using the following:
```
{% extends "filename.md" %}
```

This allows you to use Jinja's block mechanism to override sections of a document.