rkent
commented
2 months ago There is also a related issue on rosdoc2.
Let me give my opinion, but realize I am not a member of the powers-that-be, just a guy who has done a lot of work on rosdoc2 lately.
I view rosindex as the place you would go to find a package that interests you, and rosdoc2 as the place you should go to actually figure out how to use a package. Now until recently rosdoc2 has been way underdeveloped compared to rosindex, so rosindex was more useful. But that is changing.
Given that division, rosdoc2 is the place for detailed tutorial information, not rosindex. So I don't believe that the extensive Tutorials section of rosindex metadata belongs in rosindex, but rather whatever is defined should be in rosdoc2. Also, following my comment in the aforementioned rosdoc2 issue, that the starting place for the effort should be a "Tutorials" url in package.xml
<url type="tutorials">https://example.com/tutorials</url>and then add the link to that page in rosindex, similar to what is described in this PR. But I don't think that assuming rosdoc2 will generate a tutorial.html at the root level is the right approach.
This pull request is aimed at replacing at both #295 and #93, by showing immediate access to tutorials to the user which are connected through the docs. I interpret
Source Tutorialsto be any tutorials aligned with the orignal documentation of the package so, a Tutorials Section of the documentation.There are multiple packages which have tutorials in their docs, which clients can use on site (which makes sense IMO) - image_pipeline and a growing effort in geometry2. This is a work in a progress pull request as I would like to test the waters to see if this type of stuff could be standardized, becuase if all packages generated documentation (tutorials) in this way instead of something like these offsite tutorials, it would be much easier to manage everything. Especially if generating documentation through something like rosdoc2 becomes more prevalent, so I'm going to start there.