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!make <command>-with-api
exists, which in addition builds the doxygen
api.First, you need to fetch the reviewer stats from ros2_control org. To do so, you need to have a github token with the repo
scope. Then run
export GITHUB_TOKEN=<your token>
python3 ./make_help_scripts/create_pr_stats.py
which will create ~/reviews/reviewers_stats_with_graph.html
. Then you can build the documentation as usual, it will copy the file from this folder.
sudo apt install doxygen graphviz
python3 -m pip install -r requirements.txt
cd
git clone https://github.com/PickNikRobotics/generate_parameter_library.git
cd generate_parameter_library/generate_parameter_library_py/
python3 -m pip install .
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.)
make html-all-subrepos
inside control.ros.org.
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 the control.ros.org/doc/
folder and run ln -s <path to ros2_control> .
make html
inside control.ros.org.make multiversion
inside control.ros.org.
The building of multiversion consists of several steps. The scripts are located inside the make_help_scripts
folder.
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 subrepositories are visible to multiversion.sphinx-multiversion
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
deploy_defines
To add subrepositories change 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.