search

ros-infrastructure / rosdoc2

Command-line tool for generating documentation for ROS 2 packages.
Apache License 2.0
29 stars 9 forks source link

include package readme in landing page #61

Closed ottojo closed 2 months ago

ottojo commented 4 months ago

I implemented this for a specific package in https://github.com/teamspatzenhirn/rviz_2d_overlay_plugins/pull/19, and saw that a feature like this was already requested/investigated in #22 . This does work with relative paths to images, i have not tested it for links to more markdown pages.

This is just a rough hack so far, at least the path-handling has to be cleared up a bit i think :smile:

Any feedback and discussion is appreciated, i think including the readme is a good "random try" at pulling in existing information into the docs for packages without any further configuration, and might be desired to reduce duplication even once a package adds more docs (although i think lowering the barrier to and establishing a culture of deliberately writing docs beyond the readme should be the main goal).

rkent commented 4 months ago

I did something very similar in my (abandoned) work two years ago to try to improve rosdoc2. The initial commit to process standard documents is https://github.com/rkent/rosdoc2/commit/4b2872b38749eb48a111f9b4233610129a14ae28 The last work on this branch is https://github.com/rkent/rosdoc2/commits/rkent/jinja-templates

Some general comments here. There are not just markdown READMEs, but also rst versions. It is fairly trivial so support both. See for example https://github.com/ros-drivers/nmea_msgs but there are many others.

Also, README is not the only standard document. While you are searching for that, it is fairly trivial to generalize it to also get other standard documents: ["readme", "license", "contributing", "changelog"]. Some of those might end up being plain text, so it is good to support that as well.

rkent commented 2 months ago

This should be closed as completed in PR #98

ottojo commented 2 months ago

Nice, great to see this idea implemented properly! It's also great to see a lot of activity around rosdoc2 lately. Is there somewhere to read up on the long term goals or current plans/roadmap?

rkent commented 2 months ago

I could not really concretely discuss plans until I knew if the concept of jinja templates was going to fly. Well it flew, so now the big picture is much clearer. I'm also almost done with the proposed changes, so at this point it will be better to spend my time documenting what is implemented.

This work has been landing stuff that I did two years ago, and it is mostly landed. You could see what the plan was two years ago here. We're pretty close to that now. That repo was my attempt to understand the "proper" way to structure a ROS2 project back when I was trying to convert my hobby robot from ROS1 to ROS2. rosdoc2 was clearly not in shape, so I started working on it.