ROS Resources: Documentation | Support | Discussion Forum | Index | Service Status | ros @ Robotics Stack Exchange
Ask Your Question

How do you document your ROS packages?

asked 2015-09-18 10:01:56 -0600

gaya gravatar image

There are 100s of places where one can put documentation info about their ROS package code: <documentation> strings in package.xmls, Github readme pages (assuming your code is hosted on Github), Github pages of your repos, your project website, ROS wiki pages, tutorials on ROS wiki or your website or wherever else, Sphynx doc generator and other doc tools, man pages, in-code comments, obviously, etc. etc. (of course, many of these are supposed to be used on different levels of detail). It gets especially problematic when your project is separated into multiple subprojects, each hosted in their own repository, which makes it harder to get the big picture.

So, to those few out there that actually have experience documenting their (preferably open-source) code, any hints on how you organize this for huge projects and, if the documentation is not only in one place, how do you maintain it to reflect the ongoing changes in the code?

edit retag flag offensive close merge delete

1 Answer

Sort by ยป oldest newest most voted

answered 2015-09-18 13:23:44 -0600

Airuno2L gravatar image

updated 2015-09-18 13:30:03 -0600

I don't have any experience with this and I'm not sure how up-to-date this page is: link, but it has recommendations. Also there is the rosdoc_lite tool (not to be confused with the old "rosdoc" tool.

Hope that helps.

edit flag offensive delete link more



I want to add that as a user, I much prefer when people use just the wiki and auto-generated documentation (doxygen for C++ and Sphynx or Epydoc for python). Any deviations from that like putting important info in readmes and github pages makes things unorganized imo.

Airuno2L gravatar image Airuno2L  ( 2015-09-18 13:29:28 -0600 )edit

Question Tools

1 follower


Asked: 2015-09-18 10:01:56 -0600

Seen: 579 times

Last updated: Sep 18 '15