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.