Conventions de style

This document contains the various MD and RST/Sphinx specific guidelines for the frc-docs project. For guidelines related to the various WPILib code projects, see the WPILib GitHub

Noms de fichier

N’utilisez que des caractères alphanumériques minuscules et le symbole de soustraction - (moins).

Pour les documents qui porteront le même titre pour l’équipement et la programmation, ajoutez « Hardware » ou « Software » à la fin du nom du document. IE, ultrasonics-hardware.rst

Utilisez l’extension .rst comme terminaison de nom de fichier.

Note

If you are having issues editing files with the .rst extension, the recommended text editor is VS Code with the reStructuredText extension.

Texte

Tout le contenu textuel devrait apparaître sur une seule ligne. Pour faciliter la lecture, utilisez la fonction de retour à la ligne de votre éditeur de texte.

Utilisez ces dénominations pour ces termes:

roboRIO (pas RoboRIO, roboRio, ni RoboRio)
LabVIEW (pas labview ni LabView)
Visual Studio Code (VS Code) (pas vscode, VScode, vs code, etc.)
macOS (pas Mac OS, Mac OSX, Mac OS X, Mac, Mac OS, etc.)
GitHub (pas github, Github, etc.)
PowerShell (pas powershell, Powershell, etc.)
Linux (pas linux)
Java (pas java)

Use the ASCII character set for English text. For special characters (e.g. Greek symbols) use the standard character entity sets.

Use .. math:: for standalone equations and :math: for inline equations. A useful LaTeX equation cheat sheet can be found here.

Utilisez des chaînes de caractères pour les noms de fichier, les fonctions et les noms de variable.

Use of the registered trademarks FIRST® and FRC® should follow the Policy from this page. Specifically, where possible (i.e. not nested inside other markup or in a document title), the first use of the trademarks should have the ® symbol and all instances of FIRST should be italicized. The ® symbol can be added by using .. include:: <isonum.txt> at the top of the document and then using *FIRST*\ |reg| or FRC\ |reg|.

Les termes couramment utilisés doivent être ajoutés au Glossaire FRC. Vous pouvez référencer des éléments dans le glossaire en utilisant :term:`deprecated`.

Espaces

Indentation

Une indentation doit toujours correspondre au niveau précédent d’indentation sauf si vous créez un nouveau bloc de contenu.

L’indentation d’instructions de contenu sur une nouvelle ligne .. toctree:: doit être de 3 espacements.

Lignes vierges

Il doit y avoir 1 ligne vierge séparant des blocs de texte simples et les titres de section. Il doit y avoir 1 ligne vierge séparant des blocs de texte et des directives de contenu.

Espacement intérieur

Utilisez un espacement entre les phrases.

Entêtes

Headings should be in the following structure.

# for document titles. Do not use this more than once per article.
## for document sections
### for document sub-sections
#### for document sub-sub-sections
Si vous devez subdiviser la structure davantage, vous êtes mal engagé.

Utilisez la casse de titre pour les entêtes.

Listes

Les listes doivent comporter une nouvelle ligne entre chaque niveau d’indentation. Le niveau supérieur doit avoir une indentation de 0, et les sous-listes subséquentes doivent avoir une indentation débutant au premier caractère de l’indentation précédente.

- Block one
- Block two
- Block three
  - Sub 1
  - Sub 2
- Block four

Blocs de code

Tous les blocs de code doivent être dans un langage spécifique.

```python
print("Hello!")

import antigravity
```

Exception: Du contenu dont la mise en page doit être préservée et sans langage. Utilisez plutôt text.

Follow the WPILib style guide for C++ and Java example code. For example, use two spaces for indentation in C++ and Java.

RLI (Inclusion Littéralle à distance)

Lorsque cela est possible, au lieu d’utiliser des blocs de code, un RLI doit être utilisé. Cela extrait les lignes de code directement de GitHub, le plus souvent en utilisant les exemples de programmes. Cela maintient automatiquement le code à jour avec toutes les modifications apportées. Le format d’un RLI est :

.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2025.3.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/gettingstarted/Robot.java
   :language: java
   :lines: 19-25
   :lineno-match:

.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2025.3.2/wpilibcExamples/src/main/cpp/examples/GettingStarted/cpp/Robot.cpp
   :language: c++
   :lines: 50-60
   :lineno-match:

.. remoteliteralinclude:: https://raw.githubusercontent.com/robotpy/examples/242924b3843fdcc6efc2cefa8eac7bfff8b6bc48/GettingStarted/robot.py
   :language: python
   :lines: 12-29
   :lineno-match:

Assurez-vous de créer un lien vers la version brute du fichier sur GitHub, il y a un bouton Raw pratique dans le coin supérieur droit de la page.

Note

RLIs should use a tag instead of main to ensure the documentation isn’t broken the next time there is a change to the RLIed code. If a tag hasn’t been created, use the full (40 character) commit hash.

Onglets

To create code tabs in an article, you can use the .. tab-set-code:: directive. You can use md style ``` codeblocks and rli directives inside. The format is:

.. tab-set-code::
   .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2025.3.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/gettingstarted/Robot.java
      :language: java
      :lines: 19-25
      :lineno-match:

   ```c++
   // Start the timer.
   m_timer.Start();
   // Send Field2d to SmartDashboard.
   frc::SmartDashboard::PutData(&m_field);
   // Reset the drivetrain's odometry to the starting pose of the trajectory.
   m_drive.ResetOdometry(m_trajectory.InitialPose());
   // Send our generated trajectory to Field2d.
   m_field.GetObject("traj")->SetTrajectory(m_trajectory);
   ```

Si vous avez besoin d’utiliser plus d’un onglet par langue, plusieurs RLI par langue ou des onglets de texte, vous pouvez utiliser la directive .. tab-set:: et .. tab-item::. Le format est le suivant:

.. tab-set::
   .. tab-item:: Title
      :sync: sync-id
         Content

Cet exemple utilise l’argument de synchronisation pour permettre à tous les onglets avec la même clé d’être synchronisés ensemble. Cela signifie que lorsque vous cliquez sur un onglet, tous les onglets avec la même clé s’ouvriront.

Si vous avez un mélange de directives « tab-set » et « tab-set-code » sur une page, vous pouvez les synchroniser en définissant l’identifiant de synchronisation sur les directives « tab-item » avec la valeur « tabcode-LANGUAGE ». Par exemple, un onglet Java aurait un identifiant de synchronisation de « tabcode-java ».

Avertissements

Admonitions (list here) should have their text on the same line as the admonition itself. There are exceptions to this rule, however, when having multiple sections of content inside of an admonition. Generally having multiple sections of content inside of an admonition is not recommended.

Usage correcte

.. warning:: This is a warning!

Usage INCORRECTE

.. warning::
   This is a warning!

Liens

Liens internes

Les liens internes seront générés automatiquement en se basant sur le nom de fichier ReStructuredText et sur le titre de section.

Par exemple, il y a plusieurs manières de lier les sections et les documents.

Utilisez ce format pour référencer une section de document. Vous devez utiliser le chemin absolu du document. :ref:`docs/software/hardware-apis/sensors/ultrasonics-software:Analog ultrasonics` est rendu comme Capteurs à ultrasons analogiques.

Utilisez ce format pour référencer une section du même document. Notez le trait de soulignement unique. `Images`_ est rendu comme Images.

Utilisez ce format pour référencer le niveau supérieur d’un document. Vous pouvez utiliser des chemins relatifs :doc:`build-instructions` est rendu comme Instructions de compilaton Ou pour utiliser des chemins absolus, mettez une barre oblique au début du chemin :doc:`/ docs/software/hardware-apis/sensors/ultrasonics-software` est rendu comme Ultrasons - Partie logicielle. Notez que le texte rendu est le titre de la section principale de la page cible, quel que soit le nom du fichier cible.

Lorsque vous utilisez :ref: ou :doc:, vous pouvez personnaliser le texte affiché en entourant le lien réel avec des crochets angulaires <> et en ajoutant le texte personnalisé entre le premier accent grave (backtick) ```` ` et le premier crochet angulaire <. Par exemple :ref:`texte personnalisé <docs/software/hardware-apis/sensors/ultrasonics-software:Ultrasoniques analogiques>` est rendu en texte personnalisé.

Liens externes

It is preferred to format external links as md style hyperlinks.

Hi there, [this is a link](https://example.com) and it's pretty cool!

Cependant, dans les cas où le même lien doit être référencé à plusieurs reprises, la syntaxe suivante est acceptée.

Hi there, `this is a link`_ and it's pretty cool!
..  _this is a link: https://example.com

Python API Links

Links to the RobotPY API documentation should use the following sphinx python syntax (example linking to the DriverStation API docs).

:py:class:`Python <robotpy:wpilib.DriverStation>`

This expands to be equivalent to:

[Python](https://robotpy.readthedocs.io/projects/robotpy/en/stable/wpilib/DriverStation.html#wpilib.DriverStation)

Images

Les images doivent être introduites avec 1 nouvelle ligne séparant le contenu et l’instruction.

La taille de chaque image (même au format vectoriel) ne doit pas dépasser 500 kilo-octets. Veuillez réduire la résolution d’image et utiliser un algorithme de compression efficace.

.. image:: images/my-article/my-image.png
   :alt: Always add alt text here describing the image.

Fichiers image

Les fichiers d’images doivent être stockés dans le répertoire du document, sous-répertoire document-name/images.

They should follow the naming scheme of short-description.png, where the name of the image is a short description of what the image shows. This should be less than 24 characters.

They should be of the .png or .jpg image extension. .gif is unacceptable due to storage and accessibility concerns.

Note

Accessibility is important! Images should be marked with a :alt: directive.

.. image:: images/my-document/my-image.png
   :alt: An example image

Images vectorielles

Les fichiers SVG sont supportés via l’extension Sphinx svg2pdfconverter.

Utilisez-les comme vous le feriez de tout autre format d’image.

Note

Assurez-vous que les images incorporées au document vecteur ne le gonflent pas pour dépasser la limite de 500 Ko.

.. image:: images/my-document/my-image.svg
   :alt: Always add alt text here describing the image.

Croquis Draw.io

Draw.io (also known as diagrams.net) diagrams are supported through svg files with embedded .drawio metadata, allowing the svg file to act as a source file of the diagrams, and to be rendered like a normal vector graphics file.

Utilisez-les simplement comme vous le feriez pour toute autre image vectorielle ou toute autre format d’image.

.. image:: diagrams/my-document/diagram-1.drawio.svg
   :alt: Always add alt text here describing the image.

Fichiers Draw.io

Les fichiers Draw.io suivent presque le même schéma de nomenclature que les images normales. Pour garder la trace des fichiers contenant les métadonnées .drawio intégrées, ajoutez un .drawio à la fin du nom de fichier mais avant l’extension, ce qui signifie que le nom du fichier doit être document-title-1.drawio.svg etc. De plus, les croquis ou diagrammes doivent être stockés dans le répertoire du document, dans un sous-dossier nommé diagrams.

Pour les détails concernant la sauvegarde d’un croquis ou diagramme en tant que .svg avec des métadonnées, consultez Instructions de sauvegarde pour Draw.io.

Avertissement

Ne modifiez aucun fichier du dossier diagrams ou se terminant par .drawio.svg avec un programme autre que draw.io, sinon vous risquez d’endommager les métadonnées du fichier, ce qui le rendrait inutilisable.

Extensions de fichiers

Les extensions de fichiers doivent utiliser la mise en forme du code. Par exemple, utilisez :

``.png``

Au lieu de:

.png
".png"
"``.png``"

Table des matières (TOC)

Chaque catégorie doit contenir un index.rst. Ce fichier d’index doit avoir une profondeur maxdepth de 1. Les sous-catégories sont acceptables, avec une profondeur maximale maxdepth de 1.

Le fichier index.rst de catégorie peut être ajouté au fichier index de la racine dans source/index.rst.

Exemples

# Title
This is an example article
```java
System.out.println("Hello World");
```
## Section
This is a section!

Notes importantes!

Cette liste n’est pas exhaustive et les administrateurs se réservent le droit de la modifier. Les modifications seront identifiées dans ce document.