Contribuer à la documentation ROS 2

Les contributions à ce site sont les bienvenues. Cette page explique comment contribuer à la documentation ROS 2. Assurez-vous de lire attentivement les sections ci-dessous avant de contribuer.

Le site est construit en utilisant Sphinx, et plus particulièrement en utilisant Sphinx multiversion.

Structure de la succursale

Le code source de la documentation se trouve dans le référentiel ROS 2 Documentation GitHub. Ce référentiel est configuré avec une branche par distribution ROS 2 pour gérer les différences entre les distributions. Si une modification est commune à toutes les distributions ROS 2, elle doit être apportée à la branche rolling (et sera ensuite rétroportée le cas échéant). Si une modification est spécifique à une distribution ROS 2 particulière, elle doit être apportée à la branche correspondante.

Structure source

Les fichiers source du site sont tous situés dans le sous-répertoire source. Les modèles pour divers plugins sphinx sont situés sous source/_templates. Le répertoire racine contient la configuration et les fichiers requis pour créer localement le site à des fins de test.

Construire le site localement

Commencez par installer les exigences situées dans le fichier requirements.txt :

La commande suivante effectue une installation spécifique à l’utilisateur, qui nécessite l’ajout de ~/.local/bin/ à $PATH :

pip3 install --user --upgrade -r requirements.txt

Pour que Sphinx puisse générer des diagrammes, la commande dot doit être disponible.

sudo apt update ; sudo apt install graphviz

Construire le site pour une succursale

Pour créer le site uniquement pour cette branche, tapez make html au niveau supérieur du référentiel. Il s’agit de la méthode recommandée pour tester les modifications locales.

make html

Le processus de construction peut prendre un certain temps. Pour voir la sortie, ouvrez build/html/index.html dans votre navigateur.

Vous pouvez également exécuter les tests de documentation localement (en utilisant doc8) avec la commande suivante :

make test

Création du site pour toutes les succursales

Pour construire le site pour toutes les branches, tapez make multiversion depuis la branche rolling. Cela a deux inconvénients :

  1. Le plugin multiversion ne comprend pas comment faire des builds incrémentiels, donc il reconstruit toujours tout. Cela peut être lent.

  2. Lorsque vous tapez make multiversion, il vérifiera toujours exactement les branches répertoriées dans le fichier conf.py. Cela signifie que les modifications locales ne seront pas affichées.

Pour afficher les modifications locales dans la sortie multiversion, vous devez d’abord valider les modifications dans une branche locale. Ensuite, vous devez éditer le fichier conf.py et changer la variable smv_branch_whitelist pour pointer vers votre branche.

Pages d’écriture

Le site Web de documentation de ROS 2 utilise le format reStructuredText, qui est le langage de balisage en clair par défaut utilisé par Sphinx. Cette section est une brève introduction aux concepts, à la syntaxe et aux meilleures pratiques de reStructuredText.

Vous pouvez vous référer à la ReStructuredText User Documentation pour une spécification technique détaillée.

Table des matières

Il existe deux types de directives utilisées pour la génération d’une table des matières, .. toctree:: et .. contents::. Le .. toctree :: est utilisé dans les pages de niveau supérieur comme Tutorials.rst pour définir l’ordre et la visibilité de ses pages enfants. Cette directive crée à la fois un panneau de navigation de gauche et des liens de navigation dans la page vers les pages enfants répertoriées. Il aide les lecteurs à comprendre la structure des sections de documentation distinctes et à naviguer entre les pages.

.. toctree::
   :maxdepth: 1

La directive .. contents:: est utilisée pour la génération d’une table des matières pour cette page particulière. Il analyse tous les titres présents dans une page et construit une table des matières imbriquée dans la page. Il aide les lecteurs à avoir un aperçu du contenu et à naviguer à l’intérieur d’une page.

La directive .. contents:: prend en charge la définition de la profondeur maximale des sections imbriquées. L’utilisation de :depth: 2 n’affichera que les sections et les sous-sections dans la table des matières.

.. contents:: Table of Contents
   :depth: 2
   :local:

Rubriques

Il existe quatre principaux types de titres utilisés dans la documentation. Notez que le nombre de symboles doit correspondre à la longueur du titre.

Page Title Header
=================

Section Header
--------------

2 Subsection Header
^^^^^^^^^^^^^^^^^^^

2.4 Subsubsection Header
~~~~~~~~~~~~~~~~~~~~~~~~

Nous utilisons généralement un chiffre pour numéroter les sous-sections et deux chiffres (séparés par des points) pour numéroter les sous-sous-sections dans les didacticiels et les guides pratiques.

Listes

Les étoiles * sont utilisées pour répertorier les éléments non ordonnés avec des puces et le signe dièse #. est utilisé pour répertorier les éléments numérotés. Les deux prennent en charge les définitions imbriquées et s’afficheront en conséquence.

* bullet point

  * bullet point nested
  * bullet point nested

* bullet point

#. first listed item
#. second lited item

Formatage des codes

Le code dans le texte peut être formaté à l’aide de backticks pour afficher le code surligné.

In-text code can be formatted using ``backticks`` for showing ``highlighted`` code.

Les blocs de code à l’intérieur d’une page doivent être capturés à l’aide de la directive .. code-block::. .. code-block:: prend en charge la coloration du code pour des syntaxes telles que C++, YAML, console, bash, etc. Le code à l’intérieur de la directive doit être indenté.

.. code-block:: C++

   int main(int argc, char** argv)
   {
      rclcpp::init(argc, argv);
      rclcpp::spin(std::make_shared<ParametersClass>());
      rclcpp::shutdown();
      return 0;
   }

Images

Les images peuvent être insérées en utilisant la directive .. image::.

.. image:: images/turtlesim_follow1.png