Default values for options BUILD_EXAMPLES and BUILD_DOCS

[mfep]

The following describes a discrepancy in the CMake scripts of the OpenCL-CLHPP project:

• The test suite is configured to build only if it is explicitly enabled via BUILD_TESTING and if the current project is the root CMake project (or if the project specific OPENCL_CLHPP_BUILD_TESTING option is set).
• This above is beneficial when the project is consumed by an other project, e.g. via FetchContent, because the test targets are not added. It is unlikely that the parent project is interested in running the tests of the dependent project, but still possible via the aforementioned cache variable.
• The same logic is not applied to the BUILD_EXAMPLES and BUILD_DOCS options, even though they are also likely to be unneeded by the parent project.
• An additional downside is that the current setup poses additional dependency requirements on the parent project (both the docs and the examples have a few, albeit the docs will not fail the configuration if Doxygen is not found).
• It should be considered to add the same logic to BUILD_EXAMPLES and BUILD_DOCS as seen with the BUILD_TESTING option.

[bashbaug]

I'm starting to think the best option is to simply change the default for BUILD_EXAMPLES and BUILD_DOCS from enabled to disabled. I can't think of a clever way to set things up that would have better defaults and still retain full configurability.

If we did something simlilar to what we do for testing, like...

if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME OR BUILD_EXAMPLES)

... we could also keep building the examples or the docs by default when this project is the root project, but we also wouldn't have any mechanism to disable building the samples or the docs when this project is the root project, either, and I think this type of configurability is important.

Is there a way to set the default for the option to enabled when this project is the root project, and disabled otherwise, but still allow explicitly enabling and disabling the option in both cases? I'm aware of CMakeDependentOption but this doesn't seem to do what I'd like to do since it hides the option vs. changing the default when the dependencies are not satisfied.