CMake: Update build rules to link Sphinx and Doxygen

CMakeLists.txt

@@ -21,6 +21,7 @@ set(CMAKE_PREFIX_PATH ${Trilinos_DIR} ${CMAKE_PREFIX_PATH})
 option(ENABLE_WRFTONALU "Enable WRF to Nalu Fortran conversion utility" off)
 option(ENABLE_SPHINX_DOCS "Enable Sphinx-based user/developer manual" off)
 option(ENABLE_DOXYGEN_DOCS "Enable API documentation using Doxygen" off)
+option(ENABLE_SPHINX_API_DOCS "Enable linking Doxygen API documentation to Sphinx" off)
 
 find_package(MPI REQUIRED)
 find_package(Trilinos REQUIRED)

doc/CMakeLists.txt

@@ -1,10 +1,11 @@
 
 add_custom_target(docs)
 
+if (ENABLE_DOXYGEN_DOCS)
+  add_subdirectory(doxygen)
+endif()
+
 if (ENABLE_SPHINX_DOCS)
   add_subdirectory(manual)
 endif()
 
-if (ENABLE_DOXYGEN_DOCS)
-  add_subdirectory(doxygen)
-endif()

doc/doxygen/CMakeLists.txt

@@ -15,6 +15,14 @@ else()
     OPTIONAL_COMPONENTS dot)
 endif()
 
+if (ENABLE_SPHINX_API_DOCS)
+  set(DOXYGEN_GENERATE_XML "YES"
+    CACHE STRING "Create XML tags for Sphinx Breathe")
+else()
+  set(DOXYGEN_GENERATE_XML "NO"
+    CACHE STRING "Create XML tags for Sphinx Breathe")
+endif()
+
 configure_file(Doxyfile.in Doxyfile @ONLY)
 add_custom_target(api-docs
   COMMAND ${DOXYGEN_EXECUTABLE} "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile")

doc/doxygen/Doxyfile.in

@@ -1932,7 +1932,7 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.
 
-GENERATE_XML           = NO
+GENERATE_XML           = @DOXYGEN_GENERATE_XML@
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

doc/manual/CMakeLists.txt

@@ -8,16 +8,24 @@ endif()
 
 find_package(LATEX COMPONENTS PDFLATEX BIBTEX)
 
+if (ENABLE_SPHINX_API_DOCS)
+  set(SPHINX_OPTS "-t" "use_breathe")
+else()
+  set(SPHINX_OPTS " ")
+endif()
+
 add_custom_target(sphinx-html
   COMMAND ${SPHINX_EXE} -M html
   "${CMAKE_CURRENT_SOURCE_DIR}/source" "${CMAKE_CURRENT_BINARY_DIR}"
-  -c ${CMAKE_CURRENT_SOURCE_DIR}/source)
+  -c ${CMAKE_CURRENT_SOURCE_DIR}/source ${SPHINX_OPTS})
+add_dependencies(sphinx-html api-docs)
 
 if (LATEX_FOUND)
   add_custom_target(sphinx-pdf
     COMMAND ${SPHINX_EXE} -M latexpdf
     "${CMAKE_CURRENT_SOURCE_DIR}/source" "${CMAKE_CURRENT_BINARY_DIR}"
-    -c ${CMAKE_CURRENT_SOURCE_DIR}/source)
+    -c ${CMAKE_CURRENT_SOURCE_DIR}/source ${SPHINX_OPTS})
+  add_dependencies(sphinx-pdf api-docs)
 else()
   message(WARNING "Disabling PDF generation because of missing pdflatex")
 endif()

doc/manual/source/user/installation.rst

@@ -250,6 +250,11 @@ previous section.
 
    Boolean flag to enable extract source code documentation using Doxygen. Default: OFF.
 
+.. cmakeval:: ENABLE_SPHINX_API_DOCS
+
+   Enable embedding API documentation generated from Doxygen within user and
+   developer manuals. Default: OFF.
+
 Further fine-grained control of the build environment can be achieved by using
 standard CMake flags, please see `CMake documentation
 <https://cmake.org/cmake/help/v3.9/>`_ for details regarding these variables.