QAProcess: DevelopersGuide | Review Status | PackageProposalProcess | PackageDocumentation | APIReviewProcess | DocReviewProcess | CodeReviewProcess | StackDocumentation | StackVersionPolicy | AutomatedTesting | StackReleaseProcess | WritingTutorials | Graveyard
This is an example template for documenting Stacks. We are currently refining this template with Stacks currently going through the release process. Not all sections are relevant to all Stacks. This will eventually become a Wiki template.
- Summary of stack. Should summarize what functionality a stack exports and at what level (i.e. C++ library, scripts, ROS nodes, etc...)
- ROS API
- List of packages (autogenerated)
- Related Apps (i.e. where can the user find interesting usages of your stack, if applicable)
- Dependencies (autogenerated)
- "Click here to file a bug report"
- Expected Hardware. What hardware does a stack expect? What hardware has it been tested with? What is the recommended hardware?
- Use-based tutorials. e.g. porting the nav stack to another platform, configuring TF for your robot hardware, etc...
- Video Tutorials. e.g. TF in rviz, full set of visualizations for nav stack in rviz, etc...
- Debugging and Visualization. Description of how to visualize the state of your stack and debug problems.
ROS API Documentation
We will have to develop tools like rxgraph and possibly rosdoc more to enable this sort of documentation to be produced more easily. In general, ROS API documentation should include:
- Node configurations/graphs. For each associated launch file, a graphviz image of the nodes and their connectivity. Graph should be tweaked to highlight entry/exit points. This could probably be done with a modified version of rxgraph, plus some additional editing of the dot files. Ideally, the stack would come with a documentation directory containing the .dot files.
- List of tf frames used in this stack
- List of topics used in this stack
- List of services used in this stack