Contributing to ROS 2 Documentation

Contributions to this site are most welcome. This page explains how to contribute to ROS 2 Documentation. Please be sure to read the below sections carefully before contributing.

The site is built using Sphinx, and more particularly using Sphinx multiversion.

Branch structure

The source code of documentation is located in the ROS 2 Documentation GitHub repository. This repository is set up with one branch per ROS 2 distribution to handle differences between the distributions. If a change is common to all ROS 2 distributions, it should be made to the rolling branch (and then will be backported as appropriate). If a change is specific to a particular ROS 2 distribution, it should be made to the respective branch.

Source structure

The source files for the site are all located under the source subdirectory. Templates for various sphinx plugins are located under source/_templates. The root directory contains configuration and files required to locally build the site for testing.

Building the site locally

Firstly, install requirements located in the requirements.txt file.

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

Building the site for one branch

To build the site for just this branch, type make html at the top-level of the repository. This is the recommended way to test out local changes.

make html

The build process can take some time. To see the output, open build/html/index.html in your browser.

You can also run the documentation tests locally (using doc8) with the following command:

make test

Building the site for all branches

To build the site for all branches, type make multiversion from the rolling branch. This has two drawbacks:

  1. The multiversion plugin doesn’t understand how to do incremental builds, so it always rebuilds everything. This can be slow.

  2. When typing make multiversion, it will always check out exactly the branches listed in the conf.py file. That means that local changes will not be shown.

To show local changes in the multiversion output, you must first commit the changes to a local branch. Then you must edit the conf.py file and change the smv_branch_whitelist variable to point to your branch.

Writing pages

The ROS 2 documentation website uses the reStructuredText format, which is the default plaintext markup language used by Sphinx. This section is a brief introduction to reStructuredText concepts, syntax, and best practices.

You can refer to reStructuredText User Documentation for a detailed technical specification.

Table of Contents

There are two types of directives used for the generation of a table of contents, .. toctree:: and .. contents::. The .. toctree:: is used in top-level pages like Tutorials.rst to set ordering and visibility of its child pages. This directive creates both left navigation panel and in-page navigation links to the child pages listed. It helps readers to understand the structure of separate documentation sections and navigate between pages.

.. toctree::
   :maxdepth: 1

The .. contents:: directive is used for the generation of a table of contents for that particular page. It parses all present headings in a page and builds an in-page nested table of contents. It helps readers to see an overview of the content and navigate inside a page.

The .. contents:: directive supports the definition of maximum depth of nested sections. Using :depth: 2 will only show Sections and Subsections in the table of contents.

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

Headings

There are four main Heading types used in the documentation. Note that the number of symbols has to match the length of the title.

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

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

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

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

We usually use one digit for numbering subsections and two digits (dot separated) for numbering subsubsections in Tutorials and How-To-Guides.

Lists

Stars * are used for listing unordered items with bullet points and number sign #. is used for listing numbered items. Both of them support nested definitions and will render accordingly.

* bullet point

  * bullet point nested
  * bullet point nested

* bullet point

#. first listed item
#. second lited item

Code Formatting

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

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

Code blocks inside a page need to be captured using .. code-block:: directive. .. code-block:: supports code highlighting for syntaxes like C++, YAML, console, bash, and more. Code inside the directive needs to be indented.

.. code-block:: C++

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

Images

Images can be inserted using the .. image:: directive.

.. image:: images/turtlesim_follow1.png