This post fits in with the current topic “Making package quality visible in ROS” which is being discussed in the quality working group meetings.
This post is about analysing wiki pages for packages that provide nodes. Other types of packages will most likely need other types of analysis and / or metrics.
It’s doubtful whether we can actually assess the quality of a wiki page for a ROS package (as that would most likely require an understanding of the text), but looking at some of the tools available, I have the impression that we might actually be able to say at least something quantitative about a wiki page.
First: it turns out there are actually (at least) two pages on the wiki that say something about what a good quality wiki page should contain, or at least what a wiki page consistent with other pages should contain:
Most of this is style related: use consistent naming, try to avoid introducing new styling / markup / layouts, etc. Analysing / checking this might be possible with recent deep learning techniques, but I’ll skip that for now. Things that should be (I believe) machine checkable without too much work are:
- presence of customary / required sections
- ROS API
This will be up for discussion, but a “good enough” wiki page of a package should probably contain at least the following sections (not necessarily in this order):
- Package Header (auto-generated)
- Table of Contents
- Installation instructions (could be auto-generated, ros-infrastructure/roswiki#121)
- Report a Bug (could be auto-generated)
- Tutorials (if there are none, make that explicit)
- ROS API (see below)
Checking for this is not too difficult: MoinMoin provides access to page contents through the Page class. As MoinMoin pages are plain text files stored on disk, it should also be possible to check them directly (with a script running periodically fi).
A properly documented package should list the ROS API for all provided nodes. This ROS API consists of:
- topics (published, subscribed)
- services (provided, called)
- actions (provided, called)
- parameters (read, written), and
- TF frames (required, provided)
Similar to checking for sections, presence of all of these should be checkable, either via the
Page class or scanning the page source on disk directly.
Some examples of pages that document the ROS API of their nodes (in no particular order):
To make sure that the entirety of a node’s ROS API is documented, it could be extracted using suitable queries against HAROS v3 reversed metamodel of a package and then checked against the
NodeAPI template parameters provided on the wiki page.
None of the above is currently checked by the wiki, the buildfarm or any automated system.