Ask Your Question
0

How to build documentation for ROS2 packages?

asked 2019-03-24 20:16:00 -0500

Daniel Stonier gravatar image

Wondering how, e.g. rclpy, got it's documentation built (you can find it's crystal docs here so I can build documentation for submitted packages.

There is nothing on the build farm indicative of a doc job, nor is there anything special of rclpy's package.xml apart from a dependency on sphinx.

Additionally, does the ros index always expect to be pointed at https://docs.ros2.org for apidocs?

edit retag flag offensive close merge delete

1 Answer

Sort by ยป oldest newest most voted
1

answered 2019-03-25 12:41:22 -0500

William gravatar image

currently we have a manual process to build and generate the content at docs.ros2.org :

https://github.com/ros2/docs.ros2.org...

We want to have an automated way to build documentation for any ROS 2 package (Python or CMake, doxygen or sphinx), but we don't have that yet. Setting up the ROS index was done first, and no more time has been allocated to it since then.

edit flag offensive delete link more

Comments

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.

Geoff gravatar imageGeoff ( 2019-03-25 18:37:10 -0500 )edit

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?

Daniel Stonier gravatar imageDaniel Stonier ( 2019-03-25 23:27:22 -0500 )edit

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.

Daniel Stonier gravatar imageDaniel Stonier ( 2019-03-25 23:33:08 -0500 )edit

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.

Geoff gravatar imageGeoff ( 2019-03-26 01:19:27 -0500 )edit

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 gravatar imageDirk Thomas ( 2019-03-26 12:38:07 -0500 )edit

@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?

gvdhoorn gravatar imagegvdhoorn ( 2019-03-26 12:39:39 -0500 )edit

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).

Dirk Thomas gravatar imageDirk Thomas ( 2019-03-26 12:42:28 -0500 )edit

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.

gvdhoorn gravatar imagegvdhoorn ( 2019-03-26 12:47:24 -0500 )edit

Your Answer

Please start posting anonymously - your entry will be published after you log in or create a new account.

Add Answer

Question Tools

2 followers

Stats

Asked: 2019-03-24 20:16:00 -0500

Seen: 66 times

Last updated: Mar 25