User documentation

[ijnek]

There seems to be no user documentation for catkin_pkg. The docs generated in doc/ are only available when locally compiled, and only contain auto-generated API docs with no usage details.

For a start, we could move the details provided in bloom/Tutorials/FirstTimeRelease to the docs here.

Any thoughts before proceeding with the changes?

Related to ros2/ros2_documentation#2357

[nuclearsandwich]

There actually is a site where catkin_pkg documentation is deployed as part of the "independent packages" documentation on the ROS build farm: https://docs.ros.org/en/independent/api/catkin_pkg/index.html

Many of the other ROS Infrastructure packages are represented there as well with varying degrees of quality.
This is a big area of improvement for many of the ROS infrastructure packages and I'm personally split on what the optimal approaches are:

In theory, much of the ROS Infrastructure packages are usable outside of ROS and thus ideally their documentation projects would be self-contained and hosted alongside the python module API documentation.

In practice, the primary use-cases and workflows for many of these tools is wholly ROS-focused and benefits from being adjacent to other related ROS documentation.

Polling myself at this moment, I think what I would like to see from documentation efforts is the following:

• Each project (catkin_pkg, bloom, rosdep, rospkg, rosdistro, etc) should to contain its own manual, including CLI and API documentation, which strives to be as comprehensive as possible. Maintaining (and improving on) the status quo, it should remain source and host independent from other ROS documentation.

• ROS-related workflow documentation should either be added to the project manuals under a "Using $TOOL with ROS" section and linked from ROS documentation or conversely added to the ROS documentation with links to relevant manual sections for deeper details. The latter is probably more accessible both for ROS users and ROS contributors so it's probably the way to go.

The ros2_documentation repository is becoming the de-facto home for future ROS documentation so I think a good start is improving the workflow documentation there. But I would not advocate that any reference material for tools used in those workflows be moved into that repository. I think the benefits of concentrated contributors in the ROS documentation are outweighed by the drawbacks of pulling the comprehensive documentation away the dedicated review of primary maintainers.

[ijnek]

There actually is a site where catkin_pkg documentation is deployed as part of the "independent packages" documentation on the ROS build farm: https://docs.ros.org/en/independent/api/catkin_pkg/index.html

I didn't know that! That's a good start. I wonder if there is a way to get the page showing up in google searches higher up when we search catkin_pkg. 🤔

I agree with all of your suggestions you've made. User documentation is missing for the tools and it's better late than never to have them.

catkin_tools's RTD is really nice, and something similar would be ideal.

The latter is probably more accessible both for ROS users and ROS contributors so it's probably the way to go.

I like the latter too.

The ros2_documentation repository is becoming the de-facto home for future ROS documentation so I think a good start is improving the workflow documentation there. But I would not advocate that any reference material for tools used in those workflows be moved into that repository. I think the benefits of concentrated contributors in the ROS documentation are outweighed by the drawbacks of pulling the comprehensive documentation away the dedicated review of primary maintainers.

Is this supporting the idea of having the "Using $TOOL with ROS" documentation in ros2_documentation? If so, agreed.

What I'm thinking next?

Wrtiting bloom and catkin_pkg manuals and making instructions ros2/ros2_documentation#2375 more concise by including links to those manuals.