ci: initial support to automate DocFX generation (#11270)

coryan · web-flow · commit 2110e07fdfb6 · 2023-04-13T12:51:56.000-04:00
This creates CMake targets to create the DocFX YAML files. I cannot
enable this in the build (yet), because the docfx tool needs more work.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -165,6 +165,7 @@ add_custom_target(google-cloud-cpp-protos)
 
 # Each subproject adds dependencies to this target to have their docs generated.
 add_custom_target(doxygen-docs)
+add_custom_target(all-docfx)
 
 find_package(absl CONFIG REQUIRED)
 if (${GOOGLE_CLOUD_CPP_ENABLE_GRPC})
diff --git a/ci/cloudbuild/builds/publish-docs.sh b/ci/cloudbuild/builds/publish-docs.sh
@@ -28,7 +28,7 @@ doc_args=(
   "-DCMAKE_BUILD_TYPE=Debug"
   "-DGOOGLE_CLOUD_CPP_GENERATE_DOXYGEN=ON"
   "-DGOOGLE_CLOUD_CPP_GEN_DOCS_FOR_GOOGLEAPIS_DEV=ON"
-  "-DGOOGLE_CLOUD_CPP_ENABLE=${ENABLED_FEATURES}"
+  "-DGOOGLE_CLOUD_CPP_ENABLE=internal-docfx,${ENABLED_FEATURES}"
   "-DGOOGLE_CLOUD_CPP_ENABLE_CCACHE=ON"
   "-DGOOGLE_CLOUD_CPP_ENABLE_WERROR=ON"
   "-DGOOGLE_CLOUD_CPP_DOXYGEN_CLANG_OPTIONS=-resource-dir=$(clang -print-resource-dir)"
@@ -68,6 +68,8 @@ cmake -GNinja "${doc_args[@]}" -S . -B cmake-out
 # pre-generate all the proto headers, then call doxygen.
 cmake --build cmake-out --target google-cloud-cpp-protos
 cmake --build cmake-out --target doxygen-docs
+# TODO(#11245) - enable once all the libraries work
+# cmake --build cmake-out --target all-docfx
 
 if [[ "${PROJECT_ID:-}" != "cloud-cpp-testing-resources" ]]; then
   io::log_h2 "Skipping upload of docs," \
diff --git a/ci/cloudbuild/dockerfiles/fedora-37-cmake.Dockerfile b/ci/cloudbuild/dockerfiles/fedora-37-cmake.Dockerfile
@@ -42,6 +42,9 @@ RUN dnf makecache && dnf debuginfo-install -y libstdc++
 # This is used by the docfx tool.
 RUN dnf makecache && dnf install -y pugixml-devel
 
+# This is used in the `publish-docs` build
+RUN dnf makecache && dnf install -y libxslt
+
 # Sets root's password to the empty string to enable users to get a root shell
 # inside the container with `su -` and no password. Sudo would not work because
 # we run these containers as the invoking user's uid, which does not exist in
diff --git a/cmake/GoogleCloudCppDoxygen.cmake b/cmake/GoogleCloudCppDoxygen.cmake
@@ -15,6 +15,7 @@
 # ~~~
 
 find_package(Doxygen QUIET)
+find_program(XSLTPROC xsltproc)
 
 function (google_cloud_cpp_doxygen_deploy_version VAR)
     set(VERSION "${PROJECT_VERSION}")
@@ -158,6 +159,26 @@ function (google_cloud_cpp_doxygen_targets_impl library)
     if (opt_DEPENDS)
         add_dependencies(${library}-docs ${opt_DEPENDS})
     endif ()
+
+    if (XSLTPROC AND TARGET doxygen2docfx)
+        # Create a target to compile the XML output into docfx format.
+        file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/docfx")
+        add_custom_target(
+            ${library}-docfx
+            DEPENDS ${library}-docs doxygen2docfx
+            WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/docfx"
+            COMMENT "Generate DoxFX YAML for ${library}"
+            COMMAND
+                ${XSLTPROC} -o
+                "${CMAKE_CURRENT_BINARY_DIR}/xml/${library}.doxygen.xml"
+                "${CMAKE_CURRENT_BINARY_DIR}/xml/combine.xslt"
+                "${CMAKE_CURRENT_BINARY_DIR}/xml/index.xml"
+            COMMAND
+                doxygen2docfx
+                "${CMAKE_CURRENT_BINARY_DIR}/xml/${library}.doxygen.xml"
+                "${library}" "${VERSION}")
+        add_dependencies(all-docfx ${library}-docfx)
+    endif ()
 endfunction ()
 
 function (google_cloud_cpp_doxygen_targets library)
diff --git a/cmake/GoogleCloudCppFeatures.cmake b/cmake/GoogleCloudCppFeatures.cmake
@@ -173,6 +173,10 @@ function (google_cloud_cpp_enable_deps)
     if (experimental-opentelemetry_sdk IN_LIST GOOGLE_CLOUD_CPP_ENABLE)
         list(INSERT GOOGLE_CLOUD_CPP_ENABLE 0 trace)
     endif ()
+    # Building the documentation for each library depends on the docfx program.
+    if (internal-docfx IN_LIST GOOGLE_CLOUD_CPP_ENABLE)
+        list(INSERT GOOGLE_CLOUD_CPP_ENABLE 0 internal-docfx)
+    endif ()
     set(GOOGLE_CLOUD_CPP_ENABLE
         "${GOOGLE_CLOUD_CPP_ENABLE}"
         PARENT_SCOPE)
@@ -227,6 +231,7 @@ function (google_cloud_cpp_enable_features)
     foreach (feature ${GOOGLE_CLOUD_CPP_ENABLE})
         if ("${feature}" STREQUAL "internal-docfx")
             add_subdirectory(docfx)
+            continue()
         elseif ("${feature}" STREQUAL "generator")
             add_subdirectory(generator)
         elseif ("${feature}" STREQUAL "experimental-storage-grpc")
diff --git a/docfx/README.md b/docfx/README.md
@@ -64,3 +64,28 @@ ls -l $HOME/doc-pipeline/site
 less $HOME/doc-pipeline/site/namespacegoogle.html
 less $HOME/doc-pipeline/site/indexpage.html
 ```
+
+### Testing with one or all Libraries
+
+This is a bit slow, but runs all the libraries through the docfx tool. First
+prepare the workspace for the `publish-docs` build:
+
+```
+ci/cloudbuild/build.sh -t publish-docs-pr
+```
+
+Then invoke the docfx tool in one library, for example:
+
+```
+ci/cloudbuild/build.sh -t publish-docs-pr  --docker-shell
+# Run this inside the docker shell
+cmake --build cmake-out --target storage-docfx
+```
+
+Or to generate the documents for all libraries:
+
+```
+ci/cloudbuild/build.sh -t publish-docs-pr  --docker-shell
+# Run this inside the docker shell
+cmake --build cmake-out --target all-docfx
+```
