Allow Staging Sphinx Documentation

[chapman39]

• adds new arguments to blt_add_sphinx_target to set sphinx source and conf.py dirs, as well as an explicit DEPENDS argument
• adds documentation for the motivation and how to use this new feature
• tested minimal, advanced examples, also one using conf.py.in file

[kennyweiss]

Thanks @chapman39

The PR description says

tested minimal, advanced examples, also one using conf.py.in file

but I didn't see a test.

Also, please see my comment about staging

[chapman39]

thank you for the feedback @kennyweiss .

about testing, i meant i tested the cmake macro locally for the 3 use-cases mentioned. if we want documentation testing in blt let me know. we might need to modify the host configs to include SPHINX_DIR, or something. or i can create an issue on it and we can come back to it.

[kennyweiss]

I think it's in good shape after your latest changes (i.e. highlighting in the code/user docs and RELEASE_NOTES that TARGET is now required)

[white238]

To be consistent with the rest of BLT, this should have been:

    cmake_parse_arguments(arg

Like:

blt/cmake/BLTMacros.cmake

Lines 20 to 26 in 8999632

	cmake_parse_arguments(arg
	"${options}" "${singleValuedArgs}" "${multiValuedArgs}" ${ARGN} )
	# Sanity checks
	if(NOT DEFINED arg_TARGET)
	message(FATAL_ERROR "TARGET is a required parameter for blt_set_target_folder macro")
	endif()

This makes it so all the arguments stand out, for example DOXYGEN_TARGET would have been arg_TARGET.

This isnt user facing so is easy to fix in a follow up PR. Would you mind doing one?

[white238]

The specific check should probably go first as well.

[white238]

I think you should set PROJECT_B_SOURCE_DIR here as well and just call it SPHINX_STAGE_DIR not PROJECT_A_STAGE_DIR

[chapman39]

#766