How to build documentation for ROS2 packages?

edit

We're going to be looking at documentation generation for Autoware over the next half a year or so. We haven't decided if we will use the same style as the ROS 2 documentation or the docs.ros2.org stuff or ReadTheDocs yet (we're not even sure which are valid options for us yet), but I think that in doing it for ourselves, we may be able to contribute to wider ROS documentation systems.

Wondering if you could unpack 'contribute to wider ROS documentation systems'. Are you talking about contributing to helping automate the ROS doc generation or something different entirely?

Thanks for the update William.

I wouldn't be averse to having something like a

<url type="docs">https://py-trees.readthedocs.io/en/release-1.1.x/</url>

element in package.xml that redirects the API Docs link for a package in ROS index to a different place. That would certainly fill a void in the short term till the OSRC build farm automates it and might even be a flexible option for some use cases in the future.

Are you talking about contributing to helping automate the ROS doc generation or something different entirely?

If that turns out to be what we need, then yes. We need auto-generated documentation capabilities, preferably in an extendable way.

The significant downside of hosting package documentation somewhere non central is that you are not able to search through all package documentation. For ROS 1 that is possible by hosting all generated docs on http://docs.ros.org/ The goal is to to the same for ROS 2 at some point.

@Dirk Thomas: has a central "index" of some sort been considered? That would avoid the need to host the actual documentation centrally, but would still facilitate visibility of it.

Or was that the idea with index.ros.org?

I am not sure what you mean with a central "index of some sort. Index.ros.org is central but only shows metadata and README content - not any generated content (like API docs).

One of the problems identified with the ROS 1 approach was the fact that the documentation on the wiki tends to go stale quickly. One of the suggested approaches to help avoid that was to host documentation close(r) to the code: perhaps even in the same repository. Problem with that is/was that the wiki doesn't support this sort of setup.

The advantage of the wiki is that it provides a single location to search for documentation. This would be lost if docs are stored in a distributed way.

A central index/table-of-contents with which projects/packages can be registered (in some form/way) could mitigitate this partly: it could provide a unified "view" over all registered documentation, while still allowing for that content to be hosted elsewhere.

One system that does something similar would be Sphinx using the interlinking feature.