ROS maintains package-level indexing and documentation with rosindex and rosdoc2 for repos that have entries in rosdistro. There are a variety of reasons why a package in rosdistro might not have their documentation appear, but one reason is because the author did not specify a source or doc repo in their release to rosdistro.
Are there any package authors that for some reason want to have their package released in ROS 2 but not appear in rosindex or rosdoc2?
Presently, rosindex attempts to document packages with no doc or source repo by diving into the release tracks, while rosdoc2 shows nothing. So a package like, e.g. radar_msgs has an entry in rosindex, but not in rosdoc2.
My inclination is to assume that the non-documentation status of these packages is inadvertent rather than deliberate, so I would be inclined to correct the ‘mistake’ by looking into the release entries in rosdistro, and presenting that as the source for documentation This is what rosindex does currently, but not rosdoc2.
Any thoughts on this?
Here is a list of packages with release entries but no doc or source, hence not appearing in rosdoc2:
I’d love to see every package with some kind of valid documentation, but in this case I worry that an automated tool grabbing any documentation it can find might surface incorrect documentation, leading to user confusion.
However, automation can still be useful here: Some kind of linting that informs the package maintainer would be useful. For example, opening an issue automatically in the package’s source repository.
With the goal of trying to benefit the ROS community the most by making docs available and filtering noise, it might be possible to automatically classify which packages are sufficiently active and should be promoted. The projects that meet all positive criteria and none of the negative criterial would have published docs. Here are some example criteria:
Positive criteria: At least one commit to the repo in the past year. Builds and tests passing on at least one of the current ROS distributions. Project has valid documentation.
Negative criteria: CVEs that are super critical, critical, or super high that have been open for more than 6 months. Project has been archived or superseded. Project is a fork of another project but only has one contributor.
Perhaps this is overly simplistic, but it should be able to capture the beneficial projects and filter out dead ones.
This rather unkind description of rosdoc2 makes me think you are not very familiar with it.
And I think that is also the general problem. rosdoc2 has changed a lot in the past couple of years, from a tool that really just showed reprocessed Doxygen results for C++ code, to a general landing page for ROS 2 packages displaying whatever could be reliably extracted from packages following ROS standards.
Too many package authors either made a decision to opt out of rosdoc2 based on an outdated understanding of what it was, or never really understood it in the first place. I doubt if there are any package authors who would say “YES include my package in ROS distributions, but please hide my package landing page.”
After a rather long discussion yesterday on discord, I discovered that the problem is bigger than I thought. On humble, 16% of repositories (89 of 549) are not including the rosdoc2 landing pages for their packages.
All I am asking is to confirm a policy “If your repository is included in official ROS distributions, you should expect it to be indexed by rosindex, and you should expect each package to have an official landing page under http://docs.ros.org/en/[distro]/p/” I don’t understand why that is controversial.
I maintain a development version of rosdoc2 that is more aggressive in collecting documentation, and collects many of the missing packages. Picking a few at random, here are their URLs with comment:
All in all, they are not any better or worse than the typical “official” rosdoc2 result. Frankly a very small number of package authors have paid attention to their rosdoc2 results.