catkin_tools_document
This package is an experimental documentation-builder for ROS packages, similar to rosdoc_lite. It differs in the following ways:
- It's implemented as a
catkin_toolsplugin, so it fits naturally into the developer workflow, and piggy-backs off that package's capabilities as far as package discovery, dependency resolution, and parallel execution. - Because it operates at the workspace level rather than package-by-package, it automatically handles linking up doxygen between dependent packages.
- It automatically links to cppreference for standard library functions and headers.
- It double-builds for doxygen, once without links to get the XML output of in-package symbols only, and once with all links to get the HTML output. This avoids the duplicate symbol warnings which rosdoc_lite produces.
Demonstration
Using a virtualenv is recommended if using pip. Alternatively, you can get a
system package for Ubuntu or Debian on my PPA (2022-03-17: PPA is broken/not updated for now).
pip install catkin_tools_document
mkdir -p catkin_ws/src && cd catkin_ws
rosinstall_generator ros_base --deps --tar --rosdistro noetic > src/.rosinstall
wstool up -t src
catkin document
Now open up catkin_ws/docs/index.html in the browser of your choice.
Release
# Upload to pypi
python setup.py sdist bdist_wheel
twine upload dist/*
# Upload to launchpad. Need to rebuild with signing as the built-in capability in stdeb
# isn't released yet, and I couldn't get dpkg-sig to work either for a post-build signature.
python setup.py --command-packages=stdeb.command sdist_dsc --upstream-version-suffix=focal --suite focal
cd deb_dist/*
dpkg-buildpackage -S
dput ppa:mikepurvis/catkin ../*_source.changes
