Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation site #4

Open
chapulina opened this issue Apr 25, 2022 · 3 comments · Fixed by #17 or #31
Open

Documentation site #4

chapulina opened this issue Apr 25, 2022 · 3 comments · Fixed by #17 or #31
Assignees

Comments

@chapulina
Copy link
Contributor

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
Copy link
Contributor Author

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
Copy link
Contributor Author

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

@mabelzhang
Copy link
Collaborator

mabelzhang commented Jan 12, 2023

Paraphrased from group discussion:

Focus on getting the basics in place.

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

@mabelzhang mabelzhang linked a pull request Jan 18, 2023 that will close this issue
@andermi andermi reopened this Feb 14, 2023
@mabelzhang mabelzhang linked a pull request Mar 4, 2023 that will close this issue
@andermi andermi reopened this Mar 16, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
5 participants