Ask Your Question
0

How do you document your ROS packages?

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

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
2

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

Airuno2L gravatar image

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

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

Comments

1

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

1 follower

Stats

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

Seen: 222 times

Last updated: Sep 18 '15