Don't require conf.py when user specifies a sphinx_sourcedir

[rkent]

Currently, sphinx_sourcedir does two things. First, it can specify the location of a non-standard documentation directory (like docs/ instead of doc/). Second, it signals (requires) that the user placed a conf.py in that location.

We happily create a default conf.py if their is documentation in doc/. We should do the same in non-standard locations. The need for a conf.py can be determined by searching for the file.

As a related issue, if the user specifies sphinx_sourcedir as the default location doc/, the program should behave no differently than if it was left at the default. Currently, specifying that forces the user to also have a conf.py in that location.

[rkent]

There's also another meaning of specifying sphinx_sourcedir, as pointed out indirectly by #114 (comment) Namely, currently specifying that means "Don't use the default rosdoc2 page layout, instead replace the documentation page using index.rst defined in 'sphinx_sourcedir'." As a side effect of that, a ../ link from that page refers to the root of the package API display, so ../somepackage shows the rosdoc2 page for a different package 'somepackage'.

There are a number of possible configurations that packages might need. Here are several use cases:

1. (the default): Use standard rosdoc2 layout, automatically including any documentation found in doc/ or doc/source. If conf.py is missing (which should be the normal case), specify a default (which will get wrapped in the final build).
2. (existing) specify sphinx_sourcedir: Use this folder as the root of the documentation, overriding standard rosdoc2 layout. Currently this requires that conf.py and index.rst be defined in the sphinx_sourcedir folder. The conf.py gets wrapped in the final build. There the current default for sphinx_sourcedir is None, not doc/ as we implied in Clean up default rosdoc2.yaml to show all available options, but commented out. #138

I think what needs to be added are a few other choices.

3. My documentation exists in some alternate location (like docs/) but use the default rosdoc2 layout. Create conf.py and/or index.rst for this folder if missing. This would need a new item in rosdoc2.yaml.

4. Use the files in sphinx_sourcedir to override the standard rosdoc2 layout, but add conf.py or index.rst if needed. I think we should just support this without requiring any new configuration.

5. My project has documentation built and hosted elsewhere. Don't build a website using rosdoc2, just show https://somewebsite.org instead. This would also need a new entry in rosdoc2.yaml.