After struggling myself to find information about how per-package documentation works in ROS, such as the recently updated and very nice docs for image_pipeline (Overview — image_pipeline 3.2.1 documentation), i wrote up my findings in a new guide on docs.ros.org, which is now online (thanks Kat and Chris for the feedback and reviews!): Documenting a ROS 2 package — ROS 2 Documentation: Rolling documentation
Please do check it out, and report or contribute back if any issues arise while you add package docs to your own package or help contribute some for your favourite ROS tools!
If you want to help even further, the rosdoc2 tool itself could be documented even better (there are TODOs in the readme), and i believe the current setup doesn’t have a nice solution for ROS message types and package API for python packages implemented in C++ via pybind11 or similar, but please correct me if that’s already possible.
Really good stuff, thanks a bunch. I followed your blog already to update the documentation of some of the packages I maintain, but still have a way to go.
I know I’ve said it at least three or four times, but thank you so much @ottojo!
A bunch of us had this on our TODO list and was really great to have the community step in. I also think this would make a great ROSCon short talk .
I want to point out a couple things for the community at large:
This “how to” gives a really great overview of how to set up Python and C++ API documentation for your project along with stand alone documentation (e.g. you want to write a quick start guide).
As we move away from the Wiki to docs.ros.org, it is incredibly important that package maintainers move their Wiki docs to over to their packages. What I said to a colleague the other day is, “In ROS 1 your docs lived on the wiki and in your code, in ROS 2 your docs should only live with your code.”
If you follow this “how to”, and add your package to ROS Index, your documentation will be automatically be hosted on docs.ros.org. Example
If you don’t have Sphinx docs, but have a great README file, the guide shows you how to link your README Markdown into the Spinx documentation.
We’re working on ways to better surface package-level docs on docs.ros.org. Right now everything is listed on this page. Code-level API docs are also available on docs.ros.org, like RCLCPP, and any source code that has Doxygen documentation. Down the road we would like to find a solution for all these docs to be organized and rendered. We’re still in the early phases of this effort, but I would I love to hear everyone’s opinions.
At the meta-package level (e.g. MoveIt, Nav2) we’re also figuring out a strategy. Right now meta-packages are getting their own sub-domains (e.g. nav2.ros.org). We probably need some more formal organization around this process down the road.
Please, please, please, try to lend a hand with documentation! The best place to start is with the packages and code you use every day! Even small pull requests help!
Noticed that some open-rmf packages are not listen on the index page you linked @Katherine_Scott. For example rmf_site which I have been experimenting with this month.
Not sure if this was intentional, but there may be other packages not linked with docs.ros.org too!
I am not sure what the plan is with respect to documentation for Open-RMF, which is a distinctly project of its own. I would imagine that Open-RMF ROS packages will be listed eventually. Perhaps @grey can shed some light on this.
.