Include documentation as mandatory CI (#1053)

* Add version-to-hex function

* Define doxygen macro as hex version

* Fix filenames

* Hide decltype(auto) from older doxygen

* Build doc as a precondition for full testing and suppress uploads

* Tweak options to be faster on pull and more forgiving on push

* Also upload for backports

* Fix example

.github/workflows/doc.yml

@@ -22,19 +22,29 @@ jobs:
           fetch-depth: 255
           fetch-tags: true
       - name: Configure celeritas
-        # TODO: decltype(auto) breaks doxygen :(
-        #    -DDOXYGEN_WARN_AS_ERROR="YES" \
+        # Turn warnings into errors only for PRs
+        # Disable expensive graphs for PRs also
         run: |
           mkdir build && cd build
           cmake \
             -DCELERITAS_BUILD_DOCS=ON \
+            -DCELERITAS_DOXYGEN_BUILD_TESTS=ON \
+            ${{ github.workflow == 'pr'
+             && '-DDOXYGEN_WARN_AS_ERROR="YES" -DDOXYGEN_HAVE_DOT="NO"'
+             || ''}} \
             -GNinja \
             ..
       - name: Build documentation
         working-directory: build
         run: |
           ninja doxygen
       - name: Upload pages artifacts
+        if: >-
+          ${{  github.ref_name == 'develop'
+            || contains(github.ref_name, 'backports/')
+            || contains(github.head_ref, 'release-')
+            || contains(github.head_ref, 'doc-')
+          }}
         id: upload-pages-user
         uses: actions/upload-pages-artifact@v2
         with:
@@ -62,12 +72,22 @@ jobs:
       - name: Configure celeritas
         run: |
           mkdir build && cd build
-          cmake -DCELERITAS_BUILD_DOCS=ON -GNinja ..
+          cmake \
+            -DCELERITAS_BUILD_DOCS=ON \
+            -DDOXYGEN_HAVE_DOT="NO" \
+            -DDOXYGEN_WARN_AS_ERROR="YES" \
+            -GNinja ..
       - name: Build user documentation
         working-directory: build
         run: |
           ninja doc
       - name: Upload pages artifacts
+        if: >-
+          ${{  github.ref_name == 'develop'
+            || contains(github.ref_name, 'backports/')
+            || contains(github.head_ref, 'release-')
+            || contains(github.head_ref, 'doc-')
+          }}
         id: upload-pages-user
         uses: actions/upload-pages-artifact@v2
         with:

.github/workflows/pr.yml

@@ -20,24 +20,23 @@ concurrency:
 jobs:
   build-fast:
     uses: ./.github/workflows/build-fast.yml
+  doc:
+    uses: ./.github/workflows/doc.yml
   all-prechecks:
-    needs: [build-fast]
+    needs: [build-fast, doc]
     runs-on: ubuntu-latest
     steps:
     - name: Success
       run: "true"
   build:
     needs: [all-prechecks]
     uses: ./.github/workflows/build-full.yml
-  doc:
-    if: ${{contains(github.head_ref, 'release-v') || contains(github.head_ref, 'doc-')}}
-    uses: ./.github/workflows/doc.yml
 
-  # Specifying a dependent job allows us to select a single "requires" check
+  # Specifying a dependent job allows us to select a single "requires" check in the project GitHub settings
   all:
     # Complete if jobs were skipped (but not if any failed or were cancelled)
     if: ${{ always() && !failure() && !cancelled() }}
-    needs: [build, doc]
+    needs: [build]
     runs-on: ubuntu-latest
     steps:
     - name: Success

cmake/CeleritasUtils.cmake

@@ -133,6 +133,16 @@ CMake configuration utility functions for Celeritas.
   unavailable options (e.g. CELERITAS_USE_CURAND when HIP is in use) will
   implicitly be zero.
 
+.. command:: celeritas_version_to_hex
+
+  Convert a version number to a C-formatted hexadecimal string.
+
+    celeritas_version_to_hex(<var> <version_prefix>)
+
+    The code will set a version to zero if ``<version_prefix>_VERSION`` is not
+    found. If ``<version_prefix>_MAJOR`` is defined it will use that; otherwise
+    it will try to split the version into major/minor/patch.
+
 #]=======================================================================]
 include_guard(GLOBAL)
 
@@ -423,3 +433,34 @@ function(celeritas_generate_option_config var)
 endfunction()
 
 #-----------------------------------------------------------------------------#
+
+function(celeritas_version_to_hex var version)
+  if("TRUE") #NOT DEFINED "${version}_MAJOR")
+    # Split version into components
+    string(REGEX MATCH "^([0-9]+)\\.([0-9]+)\\.([0-9]+)" _match "${${version}}")
+    if(NOT _match)
+      message(AUTHOR_WARNING
+        "Failed to parse version string for ${version}=\"${${version}}\":
+        _match=${_match}"
+      )
+    endif()
+    set(${version}_MAJOR "${CMAKE_MATCH_1}")
+    set(${version}_MINOR "${CMAKE_MATCH_2}")
+    set(${version}_PATCH "${CMAKE_MATCH_3}")
+  endif()
+  # Set any possibly empty values to zero
+  foreach(_ext MAJOR MINOR PATCH)
+    if(${version}_${_ext} STREQUAL "")
+      set(${version}_${_ext} 0)
+    endif()
+  endforeach()
+  # Add an extra 1 up front and strip it to zero-pad
+  math(EXPR _temp_version
+    "((256 + ${${version}_MAJOR}) * 256 + ${${version}_MINOR}) * 256 + ${${version}_PATCH}"
+    OUTPUT_FORMAT HEXADECIMAL
+  )
+  string(SUBSTRING "${_temp_version}" 3 -1 _temp_version)
+  set(${var} "0x${_temp_version}" PARENT_SCOPE)
+endfunction()
+
+#-----------------------------------------------------------------------------#

doc/CMakeLists.txt

@@ -35,8 +35,9 @@ set(_DOXYGEN_EXTRA_SOURCE
   "${PROJECT_BINARY_DIR}/include/celeritas_cmake_strings.h"
   "${PROJECT_BINARY_DIR}/include/celeritas_version.h"
 )
-if(CELERITAS_DEBUG AND CELERITAS_BUILD_TESTS)
-  # Add documentation for Celeritas test harnesses
+if((CELERITAS_DEBUG AND CELERITAS_BUILD_TESTS)
+  OR CELERITAS_DOXYGEN_BUILD_TESTS)
+  # Add documentation for Celeritas test harnesses when debugging or for CI
   list(APPEND _DOXYGEN_TEST_SOURCE
     "${PROJECT_SOURCE_DIR}/test"
   )
@@ -47,6 +48,8 @@ else()
   set(_DOXYGEN_TEST_SOURCE)
 endif()
 
+celeritas_version_to_hex(_doxy_version_hex DOXYGEN_VERSION)
+
 # Documentation usage
 set(DOXYGEN_FULL_PATH_NAMES NO)
 set(DOXYGEN_MACRO_EXPANSION YES)
@@ -56,7 +59,7 @@ set(DOXYGEN_DISTRIBUTE_GROUP_DOC YES)
 set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${PROJECT_SOURCE_DIR}/README.md")
 set(DOXYGEN_FORMULA_MACROFILE "${CMAKE_CURRENT_SOURCE_DIR}/_static/macros.tex")
 set(DOXYGEN_EXTRA_PACKAGES "amsmath")
-set(DOXYGEN_PREDEFINED "__DOXYGEN__")
+set(DOXYGEN_PREDEFINED "__DOXYGEN__=${_doxy_version_hex}")
 set(DOXYGEN_USE_MATHJAX YES)
 
 # Verbosity/warning levels
@@ -71,9 +74,11 @@ set(DOXYGEN_HTML_EXTRA_STYLESHEET
 set(DOXYGEN_GENERATE_HTML YES)
 set(DOXYGEN_HTML_OUTPUT "doxygen-html")
 set(DOXYGEN_CREATE_SUBDIRS YES)
-set(DOXYGEN_VERBATIM_HEADERS NO)
 set(DOXYGEN_REFERENCES_LINK_SOURCE YES)
 
+celeritas_set_default(DOXYGEN_VERBATIM_HEADERS NO)
+celeritas_set_default(DOXYGEN_MAX_DOT_GRAPH_DEPTH 2)
+
 doxygen_add_docs(doxygen
   "${PROJECT_SOURCE_DIR}/src"
   ${_DOXYGEN_EXTRA_SOURCE}

doc/main/examples/geant4.rst

@@ -48,7 +48,7 @@ Offload using a concrete G4VFastSimulationModel
 .. literalinclude:: ../../../example/accel/fastsim-offload.cc
    :start-at: #include
 
- Offload using a concrete G4VTrackingManager
+Offload using a concrete G4VTrackingManager
 --------------------------------------------
 
 .. literalinclude:: ../../../example/accel/trackingmanager-offload.cc

src/CMakeLists.txt

@@ -9,13 +9,7 @@
 #----------------------------------------------------------------------------#
 # Celeritas version
 
-# Add an extra 1 up front and strip it to zero-pad
-math(EXPR _temp_version
-  "((256 + ${PROJECT_VERSION_MAJOR}) * 256 + ${PROJECT_VERSION_MINOR}) * 256 + ${PROJECT_VERSION_PATCH}"
-  OUTPUT_FORMAT HEXADECIMAL
-)
-string(SUBSTRING "${_temp_version}" 3 -1 _temp_version)
-set(CELERITAS_VERSION "0x${_temp_version}")
+celeritas_version_to_hex(CELERITAS_VERSION PROJECT_VERSION)
 celeritas_configure_file("celeritas_version.h.in" "celeritas_version.h" @ONLY)
 
 #----------------------------------------------------------------------------#

src/orange/surf/LocalSurfaceVisitor.hh

@@ -102,6 +102,7 @@ LocalSurfaceVisitor::LocalSurfaceVisitor(ParamsRef const& params,
 {
 }
 
+#if !defined(__DOXYGEN__) || __DOXYGEN__ > 0x010908
 //---------------------------------------------------------------------------//
 /*!
  * Apply the function to the surface specified by the given ID.
@@ -121,6 +122,7 @@ LocalSurfaceVisitor::operator()(F&& func, LocalSurfaceId id)
         },
         this->get_item(params_.surface_types, surfaces_.types, id));
 }
+#endif
 
 //---------------------------------------------------------------------------//
 // PRIVATE HELPER FUNCTIONS

src/orange/transform/TransformVisitor.hh

@@ -88,6 +88,7 @@ CELER_FUNCTION TransformVisitor::TransformVisitor(ParamsRef const& params)
 {
 }
 
+#if !defined(__DOXYGEN__) || __DOXYGEN__ > 0x010908
 //---------------------------------------------------------------------------//
 /*!
  * Apply the function to the transform specified by the given ID.
@@ -111,6 +112,7 @@ TransformVisitor::operator()(F&& func, TransformId id)
         },
         tr.type);
 }
+#endif
 
 //---------------------------------------------------------------------------//
 /*!

src/orange/univ/TrackerVisitor.hh

@@ -61,6 +61,7 @@ CELER_FUNCTION TrackerVisitor::TrackerVisitor(ParamsRef const& params)
 {
 }
 
+#if !defined(__DOXYGEN__) || __DOXYGEN__ > 0x010908
 //---------------------------------------------------------------------------//
 /*!
  * Apply the function to the universe specified by the given ID.
@@ -82,6 +83,7 @@ TrackerVisitor::operator()(F&& func, UniverseId id)
         },
         params_.universe_types[id]);
 }
+#endif
 
 //---------------------------------------------------------------------------//
 }  // namespace celeritas