API review

Proposer: Brian Gerkey

Present at review:

• Ken, James, Wim, Melonee

Question / concerns / comments

• Where does each kind of documentation go?
• How do we handle API vs. usage documentation?
• What tool should be used for auto-generated Python documentation?

Meeting notes

We have several types of documentation, and two places to put them. We've arrived at the following arrangement:

Of the X marks above, the one that implies a change is the ROS API: it's currently in the Wiki. The plan is to write a script that converts, en masse, the ROS API documentation that is formatted using ClearSilver templates in the Wiki into some formal spec, to live in the package. The format of this spec is to be defined.

Several other issues were brought up, listed as tasks below.

Two open questions remain:

• Where do we put usage documentation? Should it be merged with API documentation, or separate? If it's separate, where should it live?
• What is the recommended authoring system for autogenerated Python documentation? We use a mix of epydoc and sphinx. We can continue this mix, or pick one.

These questions will be resolved in a future meeting.

Conclusion

• Develop formal spec of ROS API: https://code.ros.org/trac/ros/ticket/1935

• Write tool to convert Wiki Node docs to new formal spec, putting the result in the packages in SVN: https://code.ros.org/trac/ros/ticket/1936

• Write macro to include source files from SVN into Wiki pages (mostly for Tutorial content): https://code.ros.org/trac/ros/ticket/1937

• Find a way to insert a search box into Doxygen- and epydoc-generated pages: https://code.ros.org/trac/ros/ticket/1938

• Add support for using symbolic tags to refer to parts of code examples in the wiki, instead of raw line numbers: https://code.ros.org/trac/ros/ticket/1939

• Streamline the writing of tutorials; not sure of how to assign this

---