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

Si vous avez de la difficulté à modifier des fichiers avec l’extension .rst, l’éditeur de texte recommandé est Notepad++. Assurez-vous que les tabulations sont remplacées par des espaces, et que l’indentation est ajustée à 3.

Références à la pagination

Les références aux pages seront générées automatiquement en se basant aux noms de fichier des pages et aux titres de section.

Par exemple, avec le fichier contributing.rst et la section Page References, le référencement se fera avec :ref:`contributing:Page References`

Note

Sachez que la structure du document est préservée dans le référencement; la racine correspondant à l’emplacement du fichier conf.py. Pour accéder à des documents dans des sous-répertoires, faites précéder du chemin de répertoire le nom du fichier. IE, :ref:`docs/software/sensors/ultrasonics-sensors:Ultrasonics - Sensors`

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)

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

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

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.

  1. = pour les titres de document. À ne pas utiliser plus d”une fois par article.

  2. - pour les sections de document

  3. ^ pour des sous-sections de document

  4. ~ pour des sous-sous-sections de document

  5. 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.

  1. 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.

Avertissements

Le libellé des avertissements (liste ici) doit être sur la même ligne que l’avertissement lui-même. Il existe cependant des exceptions à cette règle, quand il y a plusieurs sections de contenu dans un même avertissement. Généralement, il n’est pas recommandé d’avoir plusieurs sections de contenu dans un avertissement.

Usage correcte

.. warning:: This is a warning!

Usage INCORRECTE

.. warning::
   This is a warning!

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 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

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.

La catégorie de fichier index.rst peut être ajoutée au fichier index de la racine dans 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.