Show user provided documentation from /doc (and maybe from /docs)

[rkent]

I've been testing my implementation of showing user docs. This is likely to be one of the more significant (and potentially controversial) implemented features.

Ultimately I think this is going to proceed by doing a trial implementation, running on an existing distro (just limited to packages that have relevant user documentation), and allowing us to examine the effects. But that is not a trivial project, so I want to see if there are any opinions here first.

Some issues:

• package.xml supports the doc_depend tag. Is that used anywhere, if so how? If that is for package docs, how does that interact with rosdoc2?
• Developer guidelines state that the /doc directory should contain all the documentation. But some packages use /docs instead. Do we support /doc and /docs?
• Should we attempt to render user docs that we find, even if they were intended to be rendered with another system?

[clalancette]

I'm of two minds about this.

On the one hand, it might be nice to automatically find these doc or docs subdirectories, and be as automagic as possible.

On the other, we may quickly run into exactly the problem you mention; finding documents that are not meant for us.

One compromise between these positions is to have a configuration in rosdoc2.yaml where users can specifically tell us where to find the documentation they want us to render. Thoughts?

[tfoote]

package.xml supports the doc_depend tag. Is that used anywhere, if so how? If that is for package docs, how does that interact with rosdoc2?

The intent of this is that these dependencies should be installed before running the documentation. We don't use it much now that rosdoc2 is more complete. But examples of this might be a tool to generate images programatically such as graphviz (not the best example as I think that rosdoc2 brings that in)

Re: Discovery of /docs vs /doc I agree that we want to provide a way for maintainers to set the directory they want to generate, as well as potentially set the generator mode for it. (aka pick straight markdown, vs rst, vs potentially another approach/engine maybe a full jekyll static site generator as a possible extension.)

[tfoote]

This would cross over with the PR #61 where you can also pick a readme and rendering type for it.

[rkent]

I've done some testing of generating documentation from the /docs folders of some real packages. The way this folder is used varies greatly, it is not simply an alternate way of spelling /doc. I will not be recommending that we render the /docs folder by default. Even adding an option is not useful, it is just as easy for a package to rename that folder to /doc if that is the intent.