Merge pull request #375 from DARMA-tasking/371-fix-documentation-issues

#371: [docs] use fixed doxygen version, add C++17 dependency, fix markup issues

.env

@@ -1,8 +1,8 @@
 REPO=lifflander1/checkpoint
 ARCH=amd64
-UBUNTU=18.04
+UBUNTU=22.04
 ULIMIT_CORE=0
-COMPILER=gcc-8
+COMPILER=gcc-11
 COMPILER_TYPE=gnu
 PROXY=
 CACHE=

ci/build_cpp.sh

@@ -60,7 +60,7 @@ then
     git clone --depth=1 "https://${token}@github.com/DARMA-tasking/DARMA-tasking.github.io"
     git clone https://github.com/mosra/m.css
     cd m.css
-    git checkout 5235066
+    git checkout 699abdd5
     cd ../
     "$MCSS/documentation/doxygen.py" Doxyfile-mcss
     CKPT_NAME=checkpoint_docs
@@ -70,7 +70,7 @@ then
     git config --global user.email "jliffla@sandia.gov"
     git config --global user.name "Jonathan Lifflander"
     git add "$CKPT_NAME"
-    git commit -m "Update checkpoint_docs (auto-build)"
+    git commit -m "Update magistrate_docs (auto-build)"
     git push origin master
 else
     time cmake --build . --target "${target}"

ci/deps/doxygen.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+set -exo pipefail
+
+if test $# -ne 1
+then
+    echo "usage: ./$0 <doxygen-version>"
+    exit 1
+fi
+
+doxygen_version=$1
+doxygen_tar_name=doxygen-"${doxygen_version}".linux.bin.tar.gz
+
+echo "${doxygen_tar_name}"
+
+wget https://sourceforge.net/projects/doxygen/files/rel-"${doxygen_version}"/"${doxygen_tar_name}"
+
+tar xzf "${doxygen_tar_name}" --one-top-level=doxygen --strip-components=1

ci/docker/ubuntu-20.04-gnu-docs.dockerfile

@@ -1,6 +1,6 @@
 
 ARG arch=amd64
-FROM ${arch}/ubuntu:20.04 as base
+FROM ${arch}/ubuntu:20.04 AS base
 
 ARG proxy=""
 ARG compiler=gcc-8
@@ -13,33 +13,33 @@ ENV DEBIAN_FRONTEND=noninteractive
 
 RUN apt-get update -y -q && \
     apt-get install -y -q --no-install-recommends \
-    ca-certificates \
-    curl \
-    cmake \
-    git \
-    mpich \
-    libmpich-dev \
-    wget \
-    ${compiler} \
-    zlib1g \
-    zlib1g-dev \
-    ninja-build \
-    doxygen \
-    unzip \
-    python3 \
-    python3-jinja2 \
-    python3-pygments \
-    texlive-font-utils \
-    ghostscript \
-    ccache && \
+        ${compiler} \
+        ca-certificates \
+        ccache \
+        curl \
+        ghostscript \
+        git \
+        libmpich-dev \
+        mpich \
+        ninja-build \
+        python3 \
+        python3-jinja2 \
+        python3-pygments \
+        texlive-font-utils \
+        unzip \
+        wget \
+        zlib1g \
+        zlib1g-dev &&\
     apt-get clean && \
     rm -rf /var/lib/apt/lists/*
 
 COPY ./ci/deps/cmake.sh cmake.sh
 RUN ./cmake.sh 3.23.4 ${arch}
-
 ENV PATH=/cmake/bin/:$PATH
-ENV LESSCHARSET=utf-8
+
+COPY ./ci/deps/doxygen.sh doxygen.sh
+RUN ./doxygen.sh 1.8.16
+ENV PATH=/doxygen/bin/:$PATH
 
 COPY ./ci/deps/gtest.sh gtest.sh
 RUN ./gtest.sh 1.8.1 /pkgs
@@ -57,9 +57,10 @@ ENV MPI_EXTRA_FLAGS="" \
     CMAKE_PREFIX_PATH="/lib/x86_64-linux-gnu/" \
     CC=mpicc \
     CXX=mpicxx \
+    LESSCHARSET=utf-8 \
     PATH=/usr/lib/ccache/:$PATH
 
-FROM base as build
+FROM base AS build
 COPY . /checkpoint
 
 ARG token

cmake/load_doxygen.cmake

@@ -5,7 +5,7 @@ if (${magistrate_doxygen_enabled})
     set(doxygen_in ${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile.in)
     set(doxygen_out ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
 
-    set(DOXYGEN_PROJECT_NAME "checkpoint")
+    set(DOXYGEN_PROJECT_NAME "magistrate")
     set(VERSION_MAJOR "1")
     set(VERSION_MINOR "0")
     set(VERSION_PATCH "0")
@@ -18,13 +18,13 @@ if (${magistrate_doxygen_enabled})
 
     configure_file(${doxygen_in} ${doxygen_out} @ONLY)
     configure_file(${doxygen_in}-mcss ${doxygen_out}-mcss @ONLY)
-    message(STATUS "checkpoint doxygen build started")
+    message(STATUS "magistrate doxygen build started")
 
     add_custom_target(
       docs ALL
       COMMAND ${DOXYGEN_EXECUTABLE} ${doxygen_out}
       WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-      COMMENT "checkpoint generating API documentation with Doxygen"
+      COMMENT "magistrate generating API documentation with Doxygen"
       VERBATIM
     )
 

docs/Doxyfile.in-mcss

@@ -14,16 +14,16 @@ XML_NS_MEMB_FILE_SCOPE  = YES
 ##! M_LINKS_NAVBAR2 = \
 ##!   "annotated" \
 ##!   "files" \
-##!   "<a href=\"https://github.com/\">GitHub</a> <a href=\"https://github.com/DARMA-tasking/checkpoint\">Checkpoint</a> <a href=\"https://github.com/DARMA-tasking/checkpoint-member-analyzer\">Checkpoint Analyzer</a> <a href=\"https://github.com/DARMA-tasking/detector\">Detector</a>"
+##!   "<a href=\"https://github.com/\">GitHub</a> <a href=\"https://github.com/DARMA-tasking/magistrate\">magistrate</a> <a href=\"https://github.com/DARMA-tasking/checkpoint-member-analyzer\">Serialization Sanitizer</a>"
 
-##! ALIASES += \
-##!     "m_div{1}=@xmlonly<mcss:div xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\">@endxmlonly" \
-##!     "m_enddiv=@xmlonly</mcss:div>@endxmlonly" \
-##!     "m_span{1}=@xmlonly<mcss:span xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\">@endxmlonly" \
-##!     "m_endspan=@xmlonly</mcss:span>@endxmlonly" \
-##!     "m_class{1}=@xmlonly<mcss:class xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\" />@endxmlonly" \
-##!     "m_footernavigation=@xmlonly<mcss:footernavigation xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" />@endxmlonly" \
-##!     "m_examplenavigation{2}=@xmlonly<mcss:examplenavigation xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:page=\"\1\" mcss:prefix=\"\2\" />@endxmlonly" \
-##!     "m_keywords{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"\1\" />@endxmlonly" \
-##!     "m_keyword{3}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keyword=\"\1\" mcss:title=\"\2\" mcss:suffix-length=\"\3\" />@endxmlonly" \
-##!     "m_enum_values_as_keywords=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:enum-values-as-keywords=\"true\" />@endxmlonly"
+ALIASES += \
+    "m_div{1}=@xmlonly<mcss:div xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\">@endxmlonly" \
+    "m_enddiv=@xmlonly</mcss:div>@endxmlonly" \
+    "m_span{1}=@xmlonly<mcss:span xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\">@endxmlonly" \
+    "m_endspan=@xmlonly</mcss:span>@endxmlonly" \
+    "m_class{1}=@xmlonly<mcss:class xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\" />@endxmlonly" \
+    "m_footernavigation=@xmlonly<mcss:footernavigation xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" />@endxmlonly" \
+    "m_examplenavigation{2}=@xmlonly<mcss:examplenavigation xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:page=\"\1\" mcss:prefix=\"\2\" />@endxmlonly" \
+    "m_keywords{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"\1\" />@endxmlonly" \
+    "m_keyword{3}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keyword=\"\1\" mcss:title=\"\2\" mcss:suffix-length=\"\3\" />@endxmlonly" \
+    "m_enum_values_as_keywords=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:enum-values-as-keywords=\"true\" />@endxmlonly"

docs/md/checkpoint_learn.md

@@ -1,9 +1,9 @@
 \page ckpt_learn Learn
 
-To learn how to use *checkpoint*, several resources are available.
+To learn how to use *magistrate*, several resources are available.
 
   - Learn \subpage ckpt_learn_build
   - Read the small example programs
     - Read the \subpage ckpt_learn_examples walk-through
-    - Examine `checkpoint/examples/*`
+    - Examine `magistrate/examples/*`
   - Learn \subpage ckpt_learn_serialize

docs/md/checkpoint_learn_build.md

@@ -1,21 +1,21 @@
 \page ckpt_learn_build How to Build
 
-checkpoint can be built with `cmake`.
+magistrate can be built with `cmake`.
 
 \section ckpt_how-to-build Building
 
-To build *checkpoint*, one must obtain the following dependencies:
+To build *magistrate*, one must obtain the following dependencies:
 
 \subsection ckpt_optional-deps Optional
 
-  - gtest,   (if testing *checkpoint* is enabled)
+  - gtest,   (if testing *magistrate* is enabled)
   - MPI,   (if MPI tests are enabled)
   - [Kokkos](https://github.com/kokkos/kokkos),  (if Kokkos views need to be serialized)
   - [KokkosKernels](https://github.com/kokkos/kokkos-kernels),  (if Kokkos kernel data structures need to be serialized)
 
 \subsection ckpt_use-cmake-directly-vars Using cmake directly
 
-One may use `cmake` to build *checkpoint* once the dependencies are installed.
+One may use `cmake` to build *magistrate* once the dependencies are installed.
 The following are some options that can be provided to `cmake` to change the
 build configuration:
 
@@ -24,22 +24,22 @@ build configuration:
 | `gtest_DIR`                                          |               | Install directory for googletest              |
 | `Kokkos_DIR`                                         |               | Install directory for kokkos                  |
 | `KokkosKernels_DIR`                                  |               | Install directory for kokkoskernels           |
-| `checkpoint_tests_enabled`                           | 0             | Build *checkpoint* tests                      |
-| `checkpoint_mpi_enabled`                             | 0             | Build *checkpoint* with MPI for tests         |
-| `checkpoint_examples_enabled`                        | 0             | Build *checkpoint* examples                   |
-| `checkpoint_warnings_as_errors`                      | 0             | Make all warnings errors during build         |
-| `checkpoint_doxygen_enabled`                         | 0             | Enable doxygen generation                     |
-| `checkpoint_asan_enabled`                            | 0             | Enable address sanitizer                      |
-| `checkpoint_ubsan_enabled`                           | 0             | Enable undefined behavior sanitizer           |
-| `checkpoint_serialization_error_checking_enabled(*)` | 0             | Enable extensive serialization error checking |
+| `magistrate_tests_enabled`                           | 0             | Build *magistrate* tests                      |
+| `magistrate_mpi_enabled`                             | 0             | Build *magistrate* with MPI for tests         |
+| `magistrate_examples_enabled`                        | 0             | Build *magistrate* examples                   |
+| `magistrate_warnings_as_errors`                      | 0             | Make all warnings errors during build         |
+| `magistrate_doxygen_enabled`                         | 0             | Enable doxygen generation                     |
+| `magistrate_asan_enabled`                            | 0             | Enable address sanitizer                      |
+| `magistrate_ubsan_enabled`                           | 0             | Enable undefined behavior sanitizer           |
+| `magistrate_serialization_error_checking_enabled(*)` | 0             | Enable extensive serialization error checking |
 | `CODE_COVERAGE`                                      | 0             | Generate code coverage report                 |
 
-* note that if `checkpoint_serialization_error_checking_enabled` is not explicitly enabled or disabled, it will be **enabled** for `Debug` and `RelWithDebInfo` builds and disabled for others.
+* note that if `magistrate_serialization_error_checking_enabled` is not explicitly enabled or disabled, it will be **enabled** for `Debug` and `RelWithDebInfo` builds and disabled for others.
 
 \subsection using-the-build-script Using the Build Script
 
-Instead of running `cmake`, one may invoke the `checkpoint/ci/build_cpp.sh`
-script which will run `cmake` for *checkpoint* with environment variables for
+Instead of running `cmake`, one may invoke the `magistrate/ci/build_cpp.sh`
+script which will run `cmake` for *magistrate* with environment variables for
 most configuration parameters.
 
 \subsubsection building-environment-variables Build Script Environment Variables
@@ -54,27 +54,27 @@ most configuration parameters.
 | `MAGISTRATE_DOXYGEN_ENABLED`                      | 0             | Enable doxygen generation                         |
 | `MAGISTRATE_ASAN_ENABLED`                         | 0             | Enable building with address sanitizer            |
 | `MAGISTRATE_UBSAN_ENABLED`                        | 0             | Enable building with undefined behavior sanitizer |
-| `MAGISTRATE_TESTS_ENABLED`                        | 1             | Enable checkpoint tests                           |
-| `MAGISTRATE_EXAMPLES_ENABLED`                     | 1             | Enable checkpoint examples                        |
+| `MAGISTRATE_TESTS_ENABLED`                        | 1             | Enable magistrate tests                           |
+| `MAGISTRATE_EXAMPLES_ENABLED`                     | 1             | Enable magistrate examples                        |
 | `MAGISTRATE_WARNINGS_AS_ERRORS`                   | 0             | Make all warnings errors during build             |
 | `MAGISTRATE_SERIALIZATION_ERROR_CHECKING_ENABLED` | 0             | Enable extensive error checking of serialization  |
-| `MAGISTRATE_MPI_ENABLED`                          | 1             | Enable checkpoint MPI for testing                 |
+| `MAGISTRATE_MPI_ENABLED`                          | 1             | Enable magistrate MPI for testing                 |
 
 * note that if `MAGISTRATE_SERIALIZATION_ERROR_CHECKING_ENABLED` is not explicitly enabled or disabled, it will be **enabled** for `Debug` and `RelWithDebInfo` builds and disabled for others.
 
 With these set, invoke the script with two arguments: the path to the
-*checkpoint* root directory and the build path. Here's an example assuming that
-*checkpoint* is cloned into `/usr/src/checkpoint` with trace enabled in debug mode.
+*magistrate* root directory and the build path. Here's an example assuming that
+*magistrate* is cloned into `/usr/src/magistrate` with trace enabled in debug mode.
 
 **Usage for building:**
 
 ```bash
-$ checkpoint/ci/build_cpp.sh <full-path-to-checkpoint-source> <full-path-to-build-dir>
+$ magistrate/ci/build_cpp.sh <full-path-to-magistrate-source> <full-path-to-build-dir>
 ```
 
 \subsection docker-build Building with docker containerization
 
-The easiest way to build *checkpoint* is by using `docker` with the available
+The easiest way to build *magistrate* is by using `docker` with the available
 containers that contain the proper compilers, MPI, and all other
 dependencies. First, install `docker` on the system. On some systems,
 `docker-compose` might also need to be installed.
@@ -88,7 +88,7 @@ Nvidia) and compiler version, Linux distro (ubuntu or alpine), and distro
 version.
 
 The default set of the docker configuration options is located in
-`checkpoint/.env`, which `docker-compose` will read.
+`magistrate/.env`, which `docker-compose` will read.
 
 ```
 # Variables:
@@ -103,10 +103,10 @@ The default set of the docker configuration options is located in
 #   UBUNTU={18.04, 20.04}
 #   ULIMIT_CORE=0
 #
-# DARMA/checkpoint Configuration Variables:
-#   MAGISTRATE_TESTS=1                        # Enable checkpoint tests
-#   MAGISTRATE_EXAMPLES=1                     # Enable checkpoint examples
-#   MAGISTRATE_MPI=1                          # Enable checkpoint MPI tests
+# DARMA/magistrate Configuration Variables:
+#   MAGISTRATE_TESTS=1                        # Enable magistrate tests
+#   MAGISTRATE_EXAMPLES=1                     # Enable magistrate examples
+#   MAGISTRATE_MPI=1                          # Enable magistrate MPI tests
 #   MAGISTRATE_WARNINGS_AS_ERRORS=0           # Treat warnings as errors in compilation
 #   MAGISTRATE_ASAN=0                         # Enable address sanitizer in build
 #   MAGISTRATE_UBSAN=0                        # Enable undefined behavior sanitizer in build
@@ -121,16 +121,16 @@ ubuntu. Or, to speed up the build process, the base container can be pulled for
 many of the common configurations: `docker-compose pull ubuntu-cpp`.
 
 ```bash
-$ cd checkpoint
+$ cd magistrate
 $ docker-compose run -e BUILD_TYPE=debug ubuntu-cpp
 ```
 
 For an interactive build with ubuntu, where one can build, debug, and run
 `valgrind`, etc:
 
 ```bash
-$ cd checkpoint
+$ cd magistrate
 $ docker-compose run -e BUILD_TYPE=debug ubuntu-cpp-interactive
-# /checkpoint/ci/build_cpp.sh /checkpoint /build
-# /checkpoint/ci/test_cpp.sh /checkpoint /build
+# /magistrate/ci/build_cpp.sh /magistrate /build
+# /magistrate/ci/test_cpp.sh /magistrate /build
 ```

docs/md/checkpoint_learn_example_2.md

@@ -1,6 +1,6 @@
 \page ckpt_learn_ex2 Program Example 2
 
-The full code for this *checkpoint* example can be found here:
+The full code for this *magistrate* example can be found here:
 `examples/checkpoint_example_2.cc`
 
 \subsubsection ex2 Example source code:

docs/md/checkpoint_learn_example_2_nonintrusive.md

@@ -2,7 +2,7 @@
 
 \attention All Non-Intrusive serialize methods <b>MUST</b> be placed in the namespace of type which they serialize.
 
-The full code for this *checkpoint* example can be found here:
+The full code for this *magistrate* example can be found here:
 `examples/checkpoint_example_2_nonintrusive.cc`
 
 \subsubsection ex2 Example source code:

docs/md/checkpoint_learn_example_3.md

@@ -1,6 +1,6 @@
 \page ckpt_learn_ex3 Program Example 3
 
-The full code for this *checkpoint* example can be found here:
+The full code for this *magistrate* example can be found here:
 `examples/checkpoint_example_3.cc`
 
 \subsubsection ex3 Example source code:

docs/md/checkpoint_learn_example_3_nonintrusive.md

@@ -2,7 +2,7 @@
 
 \attention All Non-Intrusive serialize methods <b>MUST</b> be placed in the namespace of type which they serialize.
 
-The full code for this *checkpoint* example can be found here:
+The full code for this *magistrate* example can be found here:
 `examples/checkpoint_example_3_nonintrusive.cc`
 
 \subsubsection ex3 Example source code:

docs/md/checkpoint_learn_example_polymorphic_macro_nonintrusive.md

@@ -2,7 +2,7 @@
 
 \attention All Non-Intrusive serialize methods <b>MUST</b> be placed in the namespace of type which they serialize.
 
-The full code for this *checkpoint* example can be found here:
+The full code for this *magistrate* example can be found here:
 `examples/checkpoint_example_polymorphic_macro_nonintrusive.cc`
 
 \subsubsection ex6 Example source code:

docs/md/checkpoint_learn_example_polymorphic_nonintrusive.md

@@ -2,7 +2,7 @@
 
 \attention All Non-Intrusive serialize methods <b>MUST</b> be placed in the namespace of type which they serialize.
 
-The full code for this *checkpoint* example can be found here:
+The full code for this *magistrate* example can be found here:
 `examples/checkpoint_example_polymorphic_nonintrusive.cc`
 
 \subsubsection ex5 Example source code:

docs/md/checkpoint_learn_example_traversal.md

@@ -1,6 +1,6 @@
 \page ckpt_learn_ex7_traversal Program Example Traversal
 
-The full code for this *checkpoint* example can be found here:
+The full code for this *magistrate* example can be found here:
 `examples/checkpoint_example_traversal.cc`
 
 \subsubsection ex7 Example source code:

docs/md/checkpoint_learn_example_traversal_nonintrusive.md

@@ -2,7 +2,7 @@
 
 \attention All Non-Intrusive serialize methods <b>MUST</b> be placed in the namespace of type which they serialize.
 
-The full code for this *checkpoint* example can be found here:
+The full code for this *magistrate* example can be found here:
 `examples/checkpoint_example_traversal_nonintrusive.cc`
 
 \subsubsection ex7 Example source code: