Improve documentation failure mode when sphinx is unavailable (#712)

* Add documentation info and clone help to readme

* Try to make documentation logic more foolproof

Don't build PDFs unless sphinx is available. Fix the sphinx rebuild logic.

CMakeLists.txt

@@ -253,7 +253,7 @@ endif()
 
 if(CELERITAS_BUILD_DOCS)
   if(NOT Doxygen_FOUND)
-    find_package(Doxygen REQUIRED)
+    find_package(Doxygen)
   endif()
 
   if(Python_FOUND)
@@ -264,13 +264,15 @@ if(CELERITAS_BUILD_DOCS)
     celeritas_check_python_module(CELERITAS_USE_Breathe breathe)
     celeritas_check_python_module(CELERITAS_USE_SphinxBibtex "sphinxcontrib.bibtex")
     celeritas_check_python_module(CELERITAS_USE_SphinxRtdTheme "sphinx_rtd_theme")
-    find_program(LATEXMK_EXECUTABLE latexmk)
+    if(CELERITAS_USE_Breathe)
+      find_program(LATEXMK_EXECUTABLE latexmk)
+    endif()
   endif()
-  if(NOT Sphinx_FOUND AND NOT Doxygen_FOUND)
-    message(SEND_ERROR "Sphinx and/or Doxygen are required for docs: setting "
+  if(NOT Doxygen_FOUND)
+    message(SEND_ERROR "Doxygen is required for building documentation: setting "
       "CELERITAS_BUILD_DOCS=OFF for next build")
     set(CELERITAS_BUILD_DOCS OFF CACHE BOOL
-      "Disabled because of missing Doxygen/Sphinx" FORCE)
+      "Disabled because of missing Doxygen" FORCE)
   endif()
 endif()
 

README.md

@@ -13,7 +13,8 @@ combination of [static RST documentation](doc/index.rst) and Doxygen-markup
 comments in the source code itself. The full [Celeritas user
 documentation][user-docs] (including selected code documentation incorporated
 by Breathe) and the [Celeritas code documentation][dev-docs] are mirrored on
-our GitHub pages site. You can generate these yourself by
+our GitHub pages site. You can generate these yourself (if the necessary
+prerequisites are installed) by
 setting the `CELERITAS_BUILD_DOCS=ON` configuration option and running `ninja
 doc` (user) or `ninja doxygen` (developer). A continuously updated version of
 the [static Celeritas user documentation][rtd] (without API documentation) is
@@ -46,7 +47,8 @@ development.
 
 As an example, if you have the [Spack][spack] package manager
 installed and want to do development on a CUDA system with Volta-class graphics
-cards, execute the following steps:
+cards, execute the following steps from within the cloned Celeritas source
+directory:
 ```console
 # Set up CUDA (optional)
 $ spack external find cuda
@@ -97,4 +99,7 @@ If using Celeritas in your work, we ask that you cite the code using its
 
 Additional references for code implementation details, benchmark problem
 results, etc., can be found in our continually evolving [citation
-file](doc/_static/celeritas.bib).
+file](doc/_static/celeritas.bib). An [exhaustive list of Celeritas presentations
+](https://github.com/celeritas-project/celeritas-docs/blob/main/presentations/presentations.bib)
+authored by (or with content authored by) core team members is available in our
+documents repo.

doc/CMakeLists.txt

@@ -91,7 +91,7 @@ if(NOT Sphinx_FOUND)
         "${CMAKE_COMMAND}"
         -UCELERITAS_PYTHONPATH
         -UCELERITAS_CHECK_PYTHON_MODULE_sphinx
-        -DCELERITAS_PYTHONPATH_RERUN
+        -DCELERITAS_PYTHONPATH_RERUN:BOOL=ON
         "${CMAKE_BINARY_DIR}"
       COMMENT "Rerunning CMake because Sphinx was not found"
       ${ARGN}
@@ -213,42 +213,47 @@ install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html/"
 set(_doc_tex "${CMAKE_CURRENT_BINARY_DIR}/latex/Celeritas.tex")
 celeritas_build_sphinx(latex "${_doc_tex}")
 
-# Download ornltm class
-ExternalProject_Add(ornltm
-  GIT_REPOSITORY https://code.ornl.gov/s3j/ornltm.git
-  GIT_TAG 05a4b22f104abd53ac7cae72fe03768710b56b86
-  CONFIGURE_COMMAND ""
-  BUILD_COMMAND ""
-  INSTALL_COMMAND ""
-  SOURCE_DIR "${_ORNLTM_BASE}"
-)
+if(Sphinx_FOUND)
+  # Download ornltm class
+  ExternalProject_Add(ornltm
+    GIT_REPOSITORY https://code.ornl.gov/s3j/ornltm.git
+    GIT_TAG 05a4b22f104abd53ac7cae72fe03768710b56b86
+    CONFIGURE_COMMAND ""
+    BUILD_COMMAND ""
+    INSTALL_COMMAND ""
+    SOURCE_DIR "${_ORNLTM_BASE}"
+  )
 
-# Generate header
-set(_header_pdf "${CMAKE_CURRENT_BINARY_DIR}/latex/ornltm-header-celeritas.pdf")
-celeritas_build_latex(
-  "${CMAKE_CURRENT_SOURCE_DIR}/_static/ornltm-header-celeritas.tex"
-  "${_header_pdf}"
-  COMMENT "Building tech memo header"
-  DEPENDS ornltm
-)
+  # Generate header
+  set(_header_pdf "${CMAKE_CURRENT_BINARY_DIR}/latex/ornltm-header-celeritas.pdf")
+  celeritas_build_latex(
+    "${CMAKE_CURRENT_SOURCE_DIR}/_static/ornltm-header-celeritas.tex"
+    "${_header_pdf}"
+    COMMENT "Building tech memo header"
+    DEPENDS ornltm
+  )
 
-# Generate header
-set(_footer_pdf "${CMAKE_CURRENT_BINARY_DIR}/latex/ornltm-footer.pdf")
-celeritas_build_latex(
-  "${CMAKE_CURRENT_SOURCE_DIR}/_static/ornltm-footer.tex"
-  "${_footer_pdf}"
-  COMMENT "Building tech memo footer"
-  DEPENDS ornltm
-)
+  # Generate header
+  set(_footer_pdf "${CMAKE_CURRENT_BINARY_DIR}/latex/ornltm-footer.pdf")
+  celeritas_build_latex(
+    "${CMAKE_CURRENT_SOURCE_DIR}/_static/ornltm-footer.tex"
+    "${_footer_pdf}"
+    COMMENT "Building tech memo footer"
+    DEPENDS ornltm
+  )
 
-# Generate PDF
-set(_doc_pdf "${CMAKE_CURRENT_BINARY_DIR}/latex/Celeritas.pdf")
-celeritas_build_latex(
-  Celeritas
-  "${_doc_pdf}"
-  COMMENT "Building PDF documentation from LaTeX"
-  DEPENDS "${_doc_tex}" "${_header_pdf}" "${_footer_pdf}" ornltm
-)
+  # Generate PDF
+  set(_doc_pdf "${CMAKE_CURRENT_BINARY_DIR}/latex/Celeritas.pdf")
+  celeritas_build_latex(
+    Celeritas
+    "${_doc_pdf}"
+    COMMENT "Building PDF documentation from LaTeX"
+    DEPENDS "${_doc_tex}" "${_header_pdf}" "${_footer_pdf}" ornltm
+  )
+else()
+  # No sphinx available: don't confuse people by downloading PDF classes
+  set(_doc_pdf "${_doc_tex}")
+endif()
 
 add_custom_target(doc_pdf DEPENDS "${_doc_pdf}")
 if(CELERITAS_USE_BREATHE)

doc/installation.rst

@@ -114,23 +114,36 @@ Building Celeritas
 ==================
 
 Once the Celeritas Spack environment has been installed, set your shell's environment
-variables (``PATH``, ``CMAKE_PREFIX_PATH``, ...) by activating it. Then, you
-can configure, build, and test using the provided helper script:
+variables (``PATH``, ``CMAKE_PREFIX_PATH``, ...) by activating it.
+
+To clone the latest development version of Celeritas:
 
 .. code-block:: console
 
+   $ git clone https://github.com/celeritas-project/celeritas.git
+
+or download it from the GitHub-generated `zip file`_.
+
+, you can configure, build, and test using the provided helper script:
+
+.. code-block:: console
+
+   $ cd celeritas
    $ spack env activate celeritas
    $ ./scripts/build.sh base
 
 or manually with:
 
 .. code-block:: console
 
+   $ cd celeritas
    $ spack env activate celeritas
    $ mkdir build && cd build
    $ cmake ..
    $ make && ctest
 
+.. _zip file: https://github.com/celeritas-project/celeritas/archive/refs/heads/develop.zip
+
 CMake Presets
 =============