Generating Tutorials within a ROS 2 Packge

[CursedRock17]

This is more so a question related to how we create things with rosdoc2, would it be possible to create a Tutorials.rst file just like how we create an Index.rst file when a client first builds documentation with this tool? I keep seeing calls to centralize everything more, especially with the moving of everything over to docs.ros.org, so I would assume that if we create a Tutorials file it would prompt package maintainers to provide users with some various in-depth guides to using their package effectively. And by generate I don't mean develop tutorials off the bat, I mean just create a file that might say

There are no tutorials available now, come back later or contribute

Also, I wouldn't mind one bit putting in a PR to make this happen, if everybody feels this is beneficial.

[rkent]

I don't really understand this request.

Note that rosdoc2 now automatically shows documentation that you have in the standard location (doc/). If you wanted to show tutorials, one way to do this would be to create a doc/tutorials/ folder containing the tutorials. Those would then be available on rosdoc2 results, all under a 'tutorials' link.

[rkent]

I did another test, and here is another alternative.

REP 149 which defines what is in package.xml has a section with urls. rosdoc2 will now show the urls that are defined there.

Although REP 149 specifies "The type should be one of the following identifiers: website (default), bugtracker or repository." that is not enforced in catkin_pkg.package.parse_package, so alternate types are accepted. So if you add an entry to package.url like:

<url type="tutorials">https://example.com/tutorials</url>

current rosdoc2 will show that link with the title "Tutorials".

Since that violates REP 149, I suppose the official response would be this is unsupported. But perhaps we should change that.

[tfoote]

It would be great to push forward the proposal for standardized tutorial links possibly here and merging/extending with REP 149 and https://index.ros.org/contribute/metadata/#tutorials

Having infrastructure to make tutorials easier in rosdoc2 would be great for hosting the content in the repository.

Then we can provide cross refereneces from the TOC as well as rosindex.