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

Which Python doc tool works better with ROS: Epydoc or Sphinx?

asked 2012-04-25 05:11:47 -0500

joq gravatar image

updated 2014-01-28 17:12:06 -0500

ngrennan gravatar image

I have no experience with either, and would appreciate your advice. ROS supports both, so I would expect both to work reasonably well.

What do you like or dislike about Epydoc or Sphinx?

I am looking for a "best practices" recommendation. I already know Doxygen for C and C++. Epydoc syntax looks a little more like that, but I do not mind learning different syntax, if worthwhile.

edit retag flag offensive close merge delete

1 Answer

Sort by ยป oldest newest most voted
6

answered 2012-04-25 08:44:40 -0500

kwc gravatar image

They are quite different, with different purposes.

Epydoc is best if you want auto-generated API documentation. It is similar in spirit to Javadoc. Sphinx only does auto-generated if you push and pull it. A downside of Epydoc for Python is that, since it is auto-generated, it often documents too well; common tricks of importing symbols into higher-level modules don't work -- Epydoc will detect the submodule and document it that way instead. This created issues with documenting rospy.

Sphinx is best for handwritten documentation, and is probably much more popular. It is best for generating documentation that goes beyond just talking about the API and gets into usage, tutorials, etc... It is best if you want to create a family of pages and cross-reference/link them together. Most API documentation you see in Sphinx is probably handwritten (e.g. click 'Show source' on the official Python module docs). The advantage of handwritten is that you only have to document what you actually intend for people to use, and there are no issues with submodules being exposed if you don't want them to. Sphinx is also nice for writing man pages.

Doxygen is kind of a cross between Sphinx and Epydoc, though I think Doxygen puts auto-generated API documents first, then makes it possible to build up other pages.

edit flag offensive delete link more

Comments

Thanks for a great answer, Ken! That is just what I wanted to know. (I will leave the question open a while longer, so others have a chance to contribute their views.)

joq gravatar image joq  ( 2012-04-25 09:55:36 -0500 )edit

I will second using epydoc for code API stuff. Works pretty well for auto-generated documentation.

mjcarroll gravatar image mjcarroll  ( 2012-04-26 14:10:32 -0500 )edit

Question Tools

Stats

Asked: 2012-04-25 05:11:47 -0500

Seen: 1,939 times

Last updated: Apr 25 '12