This repository contains the sources for the ROS 2 documentation that is hosted at https://docs.ros.org/en. The sources from this repository are built and uploaded to the site nightly by a Jenkins job.
Contributions to this site are most welcome. Please be sure to read the below sections carefully before contributing.
The site is built using Sphinx, and more particularly using Sphinx multiversion.
pip3 install --user --upgrade -r requirements.txt
This repository is setup 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.
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.
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.
To build the site for all branches, type make multiversion from the rolling branch.
This has two drawbacks:
- The multiversion plugin doesn't understand how to do incremental builds, so it always rebuilds everything. This can be slow.
- When typing
make multiversion, it will always check out exactly the branches listed in theconf.pyfile. 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.
Macros can be used to simplify writing documentation that targets multiple distributions.
Use a macro by including the macro name in curly braces.
For example, when generating the docs for Rolling on the rolling branch:
| Use | Becomes (for Rolling) | Example |
|---|---|---|
| {DISTRO} | rolling | ros-{DISTRO}-pkg |
| {DISTRO_TITLE} | Rolling | ROS 2 {DISTRO_TITLE} |
| {DISTRO_TITLE_FULL} | Rolling Ridley | ROS 2 {DISTRO_TITLE_FULL} |
| {REPOS_FILE_BRANCH} | master | git checkout {REPOS_FILE_BRANCH} |
The same file can be used on multiple branches (i.e., for multiple distros) and the generated content will be distro-specific.
To contribute to the ROS 2 source code project please refer to the ROS 2 contributing guidelines.