Allow null user_doc_dir in rosdoc2.yaml to ignore documentation.

[rkent]

Some of the larger projects have their own documentation that is built independently of rosdoc2. Rather than trying to duplicate their efforts, we should just allow the projects to add their own link in the 'documentation' area of rosdoc2.

This has the downside that the user leaves the rosdoc2 site, but I still think it is the better option for these projects.

When this PR is built, it should not show any changes since this is a new unused option, but you could see it in the tests. In my full runs, there are a number of sites with this applied (using the previous PR --yaml-extend): pinocchio, fastrtps, beluga, ign_rviz, grbl_ros, fields2cover, depthai-ros. So for example see https://rosdoc2.rosdabbler.com/humble/fields2cover/ and check the Documentation link. (These all also have additional options applied to suppress the local building of Doxygen, which is not part of the current PR).

[tfoote]

One thought reading this quickly but not having time to fully review. We also have a documentation url in the package.xml we should make sure not to duplicate.

[rkent]

You've got a good point.

If you look at my use of this option, all of the use cases are combined with suppressing the API generation. So the concept that needs expressing is sort of "We have externally-generated extensive documentation, with our own Doxygen and/or Sphinx options that are properly executed. Don't try to guess what we want, just show our documentation."

The documentation link is more "Here's an external site that might also be helpful." They might point to the old Wiki, or just to their repo.

So there are in my mind two distinct sets of situations that need options.

[rkent]

@tfoote I thought about what you said, and I think the right thing to do is going to be to invert the meaning of this option, so the option instead disables the display of the "Documentation" link outside of the "Link" section. The usage is for large projects that have their own website that generates complete documentation using possibly the doc/ directory. Out display of that directory is then duplicative. They can the rely on the Links/Documentation exposure of their website. I'll leave the other (future PR) options of never_run_doxygen and never_run_sphinx_apidoc which disable our trying to parse their code. In most cases, those large sites already have documentation of their API in their external documentation, and our attempts to generate it can either cause very large runtimes, or crashes the whole program and causes their entire rosdoc2 entry to be lost.

[tfoote]

Yeah, I like that idea to basically make this say there's external project documentation and it should link to that instead of building locally.

[rkent]

OK I edited this as we discussed. Now you can specify user_doc_dir: null in rosdoc2.yaml, and any documentation in doc/ or doc/source/ will not appear in a Documentation section.

The intention here is for large projects that generate external documentation, using the doc/ directory of the package, to tell rosdoc2 to ignore those files. We expect (but do not require) that external documentation link to be set as in package.xml.

[rkent]

Just as an additional note, there is a PR to come that will replace the rosdoc2 output in its entirety with the external documentation. This current PR still shows the default rosdoc2 output, it just ignores anything under doc/ to reduce duplication.

[tfoote]

Sorry I missed this review in the queue. lgtm