Add guide on creating package docs #4196
Conversation
|
Just a note that we have a (very recently added) guide on migrating stuff from ros wiki - might be some overlap or relevant cross references: 8fbb74d |
There was a problem hiding this comment.
🙌🏻 THANK YOU SO MUCH.
This is fantastic. I did a quick read through and fixed a couple nitpicky things. I also added some clarifications where I thought it would help. Please feel free to be less formal in your descriptions. I think our documentation works better when it is more informal.
I am a bit busy this next week but I would love to help out more with this when I can. Perhaps once you wrap up the last two sections and I can do a final read through while attempting to apply this guide to an existing ROS 2 package that could use some improvement.
|
Thanks for the review and suggestions! I think it's now in a somewhat consistent state, so i will un-draft the PR. I removed the python-bindings part, since i dont have any experience with that (yet), but i think that would be a good future addition. edit: documenting python packages which are implemented in c++ may require more work altogether, see ros-infrastructure/rosdoc2#58 for instance |
ottojo
changed the title
There was a problem hiding this comment.
@ottojo this is fantastic and I can't thank you enough! I am a bit busy this week so I can't do a complete test run of the guide, but I did read through it, and suggest a few minor clarity / grammatical changes, otherwise it looks good to me. I want to @clalancette to get a quick read through before final merge.
Once this gets merged I would appreciate it if you made a post about this guide on ROS Discourse. I think a lot of package maintainers are really going to appreciate the work you put into this.
|
|
||
| The buildfarm hosts the documentation for every distribution separately, and periodically rebuilds it from the latest commit on the specified branch. | ||
| It is not required to tag a new release to update the hosted documentation. | ||
|
|
There was a problem hiding this comment.
@clalancette where do package API documentation builds show up on the build farm? Are they part of the package's build or a distinct entity? We should probably point out where package maintainers can check their documentation builds.
@ottojo We should probably have a line that is something like, "To view the status of your package's documentation build, please check ."
There was a problem hiding this comment.
I added a note on where to find the doc jobs on build.ros2.org 👍
There was a problem hiding this comment.
Beautiful. Thanks so much.
ottojo
force-pushed
the
package-doc-guide
branch
from
eb76b2a
to
b8000e1
Compare
There was a problem hiding this comment.
This looks good to me.
@clalancette @fujitatomoya can I get a second opinion on this before the end of the week? I'll be talking to a fair number of maintainers at ROS-I next week and I think this warrants a call out. This is extremely useful information and certainly better than the current state of affairs.
Co-authored-by: Chris Lalancette <[email protected]> Signed-off-by: Jonas Otto <[email protected]>
Co-authored-by: Chris Lalancette <[email protected]> Signed-off-by: Jonas Otto <[email protected]>
clalancette
added
the
backport-all
Co-authored-by: Chris Lalancette <[email protected]> Signed-off-by: Jonas Otto <[email protected]>
* Add guide on creating package API docs Signed-off-by: Jonas Otto <[email protected]> Co-authored-by: Chris Lalancette <[email protected]> (cherry picked from commit 84dd416)
* Add guide on creating package API docs Signed-off-by: Jonas Otto <[email protected]> Co-authored-by: Chris Lalancette <[email protected]> (cherry picked from commit 84dd416)
* Add guide on creating package API docs Signed-off-by: Jonas Otto <[email protected]> Co-authored-by: Chris Lalancette <[email protected]> (cherry picked from commit 84dd416) Co-authored-by: Jonas Otto <[email protected]>
* Add guide on creating package API docs Signed-off-by: Jonas Otto <[email protected]> Co-authored-by: Chris Lalancette <[email protected]> (cherry picked from commit 84dd416) Co-authored-by: Jonas Otto <[email protected]>
|
@ottojo you are the project's hero of the week. Thank you so much! |
This adds a guide to (creating) package documentation for ros 2 packages.
It's cobbled together from my own blog, the ros2 cookbook of @mikeferguson and the rosdoc2 readme (and source code).
Suggestions and contributions are very welcome.
The idea is to gather on this page all the required information to produce a docs page containing api docs for any supported language and written documentation in a way that is supported by the ros buildfarm for hosting on
https://docs.ros.org/<language>/<distro>/p/<package>/