Documentation site

[chapulina]

Setup a documentation site that will hold:

• A system overview with sensors and actuators, control theory introduction, details about existing models and results, links to publications, etc.
• Code documentation (messages, APIs, implementation details)
• Tutorials to get started with simulation

One promising direction is to use Read The Docs hosted on GitHub pages from this repository.

[chapulina]

Before creating something custom, we should look into the latest developments for automated ROS 2 documentation generation. The tooling lives in https://github.com/ros-infrastructure/rosdoc2 and runs for every Rolling / Humble package that has docs enabled on rosdistro. It generates a Read the Docs site that includes the API docs and can be customized to add custom pages.

Sounds very similar to what we had in mind using a custom GitHub pages setup, with the advantage that we'd have to maintain less custom boilerplate, and the resulting docs would live in the https://docs.ros.org/ domain.

A few caveats:

• It only works from Humble, and this project is currently on Galactic (which EOLs in 7 months, so we'll need to move soon anyway)
• The rosdoc2 infra is very new and not widely adopted yet. So we'd be early adopters and may run into various issues. That is the way the ROS team recommends packages be documented from now on though, so it should be worth the trouble.

[chapulina]

Here's an example of a page published with rosdoc2: https://docs.ros.org/en/rolling/p/rcpputils/

[mabelzhang]

Paraphrased from group discussion:

Focus on getting the basics in place.

• (@andermi / @hamilton8415) Tutorials are the most important and need to work.
  Tutorial for External Controller Python Template #25
• (@andermi / @hamilton8415) Need a section of specifics listing some details about all of the ROS messages, etc. ( Document all fields for all messages mbari_wec_utils#10 )
• (@andermi) Spring equations LaTeX can use Markdown
• (@andermi) License currently only has MBARI, need to add OSRF.
  update license.md to include OSRF #28
• (@quarkytale / @mabelzhang) Installation and Docker instructions
• (@hamilton8415) Add physical description needed for .sdf and plugin's to "theory" section of docs.
  Added added-mass values to .sdf files mbari_wec_gz#115

Feel free to edit this comment when PRs are opened, to point each bullet item to a PR.