Conventions de style
Ce document contient les différentes directives spécifiques à RST/Sphinx relatives au projet frc-docs. Pour les directives relatives aux différents projets codés selon la WPILib, voir 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 rST extension.
Texte
All text content should be on the same line. If you need readability, use the word-wrap function of your editor.
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)
Utilisez le jeu de caractères ASCII pour l’anglais. Pour les caractères spéciaux (e.g. symboles grecs) utilisez les jeux standards de caractères.
Utilisez .. math::
pour les équations et :math:
pour les équations intégrées. Une liste d’astuces LaTeX pour les équations est disponible ici
Utilisez des chaînes de caractères pour les noms de fichier, les fonctions et les noms de variable.
L’utilisation des marques enregistrées FIRST® et FRC® doit respecter la Politique suivante. Spécifiquement, lorsque possible (i.e. non imbriquée dans une balise ou dans le titre d’un document), la première occurrence de la marque de commerce doit porter le symbole ® et toutes les mentions de FIRST doivent être en italiques. Le symbole ® peut être ajouté en insérant .. include:: <isonum.txt>
au début du document, puis en utilisant *FIRST*\ |reg|
ou 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
There should be 1
blank line separating basic text blocks and section titles. There should be 1
blank line separating text blocks and content directives.
Espacement intérieur
Utilisez un espacement entre les phrases.
Entêtes
Les entêtes doivent présenter la structure suivante. Le soulignement d’entête doit correspondre au nombre de caractères de l’entête lui-même.
=
pour les titres de document. À ne pas utiliser plus d”une fois par article.-
pour les sections de document^
pour des sous-sections de document~
pour des sous-sous-sections de documentSi 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.
Exception: Du contenu dont la mise en page doit être préservée et sans langage. Utilisez plutôt
text
.
Respectez le Guide de formatage WPILib pour des modèles de codage C++ et Java. Par exemple, utilisez deux espacements pour les indentations en C++ et 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 :
.. rli:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.1.1-beta-3/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/ramsetecontroller/Robot.java
:language: java
:lines: 44-61
:linenos:
:lineno-start: 44
.. rli:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.1.1-beta-3/wpilibcExamples/src/main/cpp/examples/RamseteController/cpp/Robot.cpp
:language: cpp
:lines: 18-30
:linenos:
:lineno-start: 18
Make sure to link to the raw version of the file on GitHub. There is a handy Raw
button in the top right corner of the page.
Tabs
To create code tabs in an article, you can use the .. tab-set-code::
directive. You can use code-block
and rli
directives inside. The format is:
.. tab-set-code::
.. rli:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.1.1-beta-3/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/ramsetecontroller/Robot.java
:language: java
:lines: 44-61
:linenos:
:lineno-start: 44
.. code-block:: cpp
// 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);
}
If you need to use more than one tab per language, multiple RLIs per language, or text tabs, you can use the .. tab-set::
and .. tab-item::
directive. The format is:
.. tab-set::
..tab-item:: Title
:sync: sync-id
Content
This example uses the sync argument to allow all of the tabs with the same key to be synced together. This means that when you click on a tab, all of the tabs with the same key will open.
If you have a mix of tab-set
and tab-set-code
directives on a page, you can sync them by setting the sync id on the tab-item
directives to tabcode-LANGUAGE
. For example, a java tab would have a sync id of 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
Internal Links will be auto-generated based on the ReStructuredText filename and section title.
Par exemple, il y a plusieurs manières de lier les sections et les documents.
Use this format to reference a document section. You must use the absolute path of the document. :ref:`docs/software/hardware-apis/sensors/ultrasonics-software:Analog ultrasonics`
renders to Capteurs à ultrasons analogiques.
Use this format to reference a section of the same document. Note the single underscore. `Images`_
renders to Images.
Use this format to reference the top-level of a document. You can use relative paths :doc:`build-instructions`
renders to Instructions de compilaton Or to use absolute paths, put a forward slash at the beginning of the path :doc:`/docs/software/hardware-apis/sensors/ultrasonics-software`
renders to Ultrasons - Partie logicielle. Note that the text rendered is the main section title of the target page regardless of the target filename.
When using :ref:
or :doc:
you may customize the displayed text by surrounding the actual link with angle brackets <>
and adding the custom text between the first backtick `
and the first angle bracket <
. For example :ref:`custom text <docs/software/hardware-apis/sensors/ultrasonics-software:Analog ultrasonics>`
renders to custom text.
Liens externes
It is preferred to format external links as anonymous hyperlinks. The important thing to note is the two underscores appending the text. In the situation that only one underscore is used, issues may arise when compiling the document.
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
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
Image files should be stored in the document directory, sub-directory of 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
Les croquis ou diagrammes Draw.io (ou diagrams.net) sont supportés en utilisant des fichiers svg
avec métadonnées .drawio
incorporées, ce qui permet au fichier svg
d’être la source du croquis et d’être affiché comme un fichier vectoriel régulier.
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.
The category index.rst
file can then be added to the root index file located at source/index.rst
.
Exemples
Title
=====
This is an example article
.. code-block:: 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.