This folder holds the source and configuration files used to generate the
ros2_control documentation web site. The current test version of the documentation can be found here.
We use sphinx for single version and sphinx-multiversion for the multi version build of our documentation.
The doc files themselves are written in restructuredtext format (*.rst).
The documentation files for ros2_control, ros2_controllers and ros2_control_demos are located in the respective repositories themselves (called subrepositories from now on).
They have to be included inside the doc
folder.
There are make
commands available which automate the process of building and inclusion of the subrepositories for you.
NOTE: In spinx-multiverison
changes in the documentation are only visible after committing them. If you want to check them before committing, you can build a single version of the docs.
make html
- Builds a single version, changes are immediate visible. You have to include the subrepositories yourself.make html-all-subrepos
- Builds a single version, changes are immediate visible. All subrepositories are automatically included.make multiversion
- Builds multiversion version, changes are only visible after commit. Make sure to commit everything before running!- For each command, a
make <command>-with-api
exists, which in addition builds thedoxygen
api.
- If you are running inside a docker container, be sure to open a port so the website can be accessed.
- Install doxygen and graphviz:
sudo apt install doxygen graphviz
python3 -m pip install -r requirements.txt
- Building of the documentation. Depends on what you want to do. See either single version or multiversion below.
If you want to see results run: python3 -m http.server --directory <path_to_control.ros.org>/_build/html <port>
and then open a browser to localhost:<port>
(Or just open _build/html/index.html
in your browser.)
- a) Run
make html-all-subrepos
inside control.ros.org.
- b) Checkout the relevant branches for control.ros.org and ros2_control.
Either checkout ros2_control inside
control.ros.org/doc/
or softlink it there. If you want to symlink it, clone it to any location you like. Make sure you are inside thecontrol.ros.org/doc/
folder and runln -s <path to ros2_control> .
- Run
make html
inside control.ros.org.
- Run
make multiversion
inside control.ros.org.
The building of multiversion consists of several steps. The scripts are located inside the make_help_scripts
folder.
- First for each branch the subrepositories are cloned into the
doc/folder
and the corresponding branch is checked out and a temporary commit is created on the branch. This is needed, so that the documentation files located in the subrepositoies are visible to multiversion. - Then the documentation is built using
sphinx-multiversion
- After the creation, each branch is checked out again and the temporary commits are deleted.
For make multiversion-with-api
additionally, the api repository (ros2_control) is pulled and the corresponding branch is checked out. Then the api is created with doxygen
and copied to the build directory.
Note: If the building fails it is possible that the temporary commits are not deleted correctly. You then have to check the branches manually an possibly clean up by deleting the temporary commits.
If you want to change the deployed branches you have to change conf.py
and make_help_scripts/deploy_defines
.
conf.py
- Change ros_distro, distro_title, distro_title_full and repos_file_branch.
- Add/remove whitelisting: smv_branch_whitelist,smv_released_pattern, ...
- possibly add your version/branch to: distro_full_names and branch_distro (in smv_rewrite_configs)
deploy_defines
- Change branch_version
To add subrepoositories chage subrepo_url
If you want to modify or otherwise test the GitHub actions workflow locally without having to push every time to see the result, you can use the act software package to run the workflows locally. You will need to use a GitHub token as the workflows pulls external repositories. You can create one with only repo:public_repo rights here.
Once you have installed act and obtained a token for your user, run from within a local copy of this repository act -s GITHUB_TOKEN -j <build-deploy or check-build>
and enter your token in the prompt. Be sure to replace the <>
with one of the two workflow names.