ROS 2 package documentation

[kyrofa]

We’re going through the process of applying REP 2004 to the SROS2 utilities. We’re shooting for quality level 2. Part of that is package documentation-- feature documentation, API documentation etc. Where should that live? index.ros.org has installation pages and tutorials, but we see no obvious place to put package-level documentation. Do we have any established conventions in the ROS 2 world? I suspect (read: hope) this will become more of a question as folks implement REP 2004.

[ruffsl]

Ever sense the soft migration to the index site, I’ve always been a bit baffled buy the documentation model for core level ROS2 packages, let alone general community packages. It might be worth clarifying the story for package-level documentation to blaze a trail for other maintainers to follow when applying REP 2004.

ROS 2 documentation home moving to index.ros.org/doc/ros2

I’d like contribute, but I’m also still a bit confused about the organizational structure and direction of ROS2 documentation. Given that this is a soft launch, the index site will be the main entry point for ROS 2 documentation, plus the new ros2/ros2_documentation repo, some of my decision paralysis arises from: What is the expected workflow for contributing new content? E.g. are there templates I should start from, what are the expected conventions? With wiki.ros.org, we used templates fo…

[christophebedard]

I was wondering the same thing recently (also working on REP-2004-related stuff) and apparently the current setup described in this answers.ros.org answer (i.e. all manual) hasn’t changed.

I’ve written a small tool to automatically generate docs for my own project (e.g. to be uploaded on a GitHub/GitLab pages site):

• Tool https://github.com/christophebedard/gen_docs
• Example use https://gitlab.com/micro-ROS/ros_tracing/ros2_tracing-api

but of course I wish we had a universal solution that would allow anyone to upload docs to docs.ros2.org/$DISTRO/api/$PACKAGE/ etc.

I think this would be a good time, now that Foxy has been released!

[dirk-thomas]

The goal for package-level ROS 2 documentation is the same as for ROS 1 - to provide a single domain to easily discover all documentation.

We do understand the significance and the urgency of the matter - actually we are aware of this topic for quite some time. Unfortunately until now the necessary resources to develop the necessary tools and infrastructure weren’t available / other ROS 2 work items had a higher priority (e.g. specific feature development). Atm we can’t promise that Open Robotics will have the bandwidth to develop the necessary parts in the near term.

Some context about the involved parts:

• A similar infrastructure as for ROS 1 which runs documentation jobs on build.ros2.org on a per repository level and generates static documentation (html / css) for API docs as well as free-form text docs.
• Merge / cross reference this generated documentation with other available metadata (like e.g. index.ros.org).
• Coexist and cross reference content which is not ROS distro specific (like generic content in the ROS 1 wiki).
• Consolidate the different documentations parts and URLs already existing [1][2][3].
• Probably support documenting different versions of a package (e.g. latest development branch, released versions, synced versions).
• Support for tutorials being backed by actual code which can be unit tested.
• Scalable to thousands of ROS packages which https://index.ros.org/doc/ros2/ currently isn’t.
• Support to remove obsolete content (e.g. removed packages / repositories).