Add Doxygen build and fix all warnings (#164)

The C++ code was documented for some time but Doxygen build process was not included. This change now introduces Doxygen builds and fixes all documentation warnings.

Authors:
  - Peter Andreas Entschev (https://github.com/pentschev)

Approvers:
  - Jake Awe (https://github.com/AyodeAwe)
  - Charles Blackmon-Luca (https://github.com/charlesbluca)

URL: #164

Author: pentschev

.github/workflows/build.yaml

@@ -34,6 +34,20 @@ jobs:
       branch: ${{ inputs.branch }}
       date: ${{ inputs.date }}
       sha: ${{ inputs.sha }}
+  docs-build:
+    if: github.ref_type == 'branch'
+    needs: conda-cpp-build
+    secrets: inherit
+    uses: rapidsai/shared-workflows/.github/workflows/[email protected]
+    with:
+      arch: "amd64"
+      branch: ${{ inputs.branch }}
+      build_type: ${{ inputs.build_type || 'branch' }}
+      container_image: "rapidsai/ci-conda:latest"
+      date: ${{ inputs.date }}
+      node_type: "gpu-v100-latest-1"
+      run_script: "ci/build_docs.sh"
+      sha: ${{ inputs.sha }}
   upload-conda:
     needs: [conda-cpp-build]
     secrets: inherit

.github/workflows/pr.yaml

@@ -14,6 +14,7 @@ jobs:
     needs:
       - checks
       - conda-cpp-build
+      - docs-build
       - conda-cpp-tests
       - conda-python-tests
     secrets: inherit
@@ -29,6 +30,16 @@ jobs:
     uses: rapidsai/shared-workflows/.github/workflows/[email protected]
     with:
       build_type: pull-request
+  docs-build:
+    needs: conda-cpp-build
+    secrets: inherit
+    uses: rapidsai/shared-workflows/.github/workflows/[email protected]
+    with:
+      build_type: pull-request
+      node_type: "gpu-v100-latest-1"
+      arch: "amd64"
+      container_image: "rapidsai/ci-conda:latest"
+      run_script: "ci/build_docs.sh"
   conda-cpp-tests:
     needs: conda-cpp-build
     secrets: inherit

.gitignore

@@ -25,3 +25,6 @@ wheels/
 *.egg-info/
 _skbuild/
 
+## Doxygen
+cpp/doxygen/html
+cpp/doxygen/xml

.pre-commit-config.yaml

@@ -46,6 +46,27 @@ repos:
         hooks:
             - id: rapids-dependency-file-generator
               args: ["--clean"]
+      - repo: local
+        hooks:
+            - id: doxygen-check
+              name: doxygen-check
+              entry: ./ci/checks/doxygen.sh
+              files: ^cpp/include/
+              types_or: [file]
+              language: system
+              pass_filenames: false
+              verbose: true
+      - repo: https://github.com/codespell-project/codespell
+        rev: v2.2.2
+        hooks:
+            - id: codespell
+              additional_dependencies: [tomli]
+              args: ["--toml", "python/pyproject.toml"]
+              exclude: |
+                (?x)^(
+                  .*test.*|
+                  ^CHANGELOG.md$
+                )
 
 default_language_version:
       python: python3

ci/build_docs.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# Copyright (c) 2023, NVIDIA CORPORATION.
+
+set -euo pipefail
+
+rapids-logger "Create test conda environment"
+. /opt/conda/etc/profile.d/conda.sh
+
+ENV_YAML_DIR="$(mktemp -d)"
+
+rapids-dependency-file-generator \
+  --output conda \
+  --file_key docs \
+  --matrix "cuda=${RAPIDS_CUDA_VERSION%.*};arch=$(arch);py=${RAPIDS_PY_VERSION}" | tee "${ENV_YAML_DIR}/env.yaml"
+
+rapids-mamba-retry env create --force -f "${ENV_YAML_DIR}/env.yaml" -n docs
+conda activate docs
+
+rapids-print-env
+
+rapids-logger "Downloading artifacts from previous jobs"
+CPP_CHANNEL=$(rapids-download-conda-from-s3 cpp)
+
+rapids-mamba-retry install \
+  --channel "${CPP_CHANNEL}" \
+  libucxx
+
+export RAPIDS_VERSION_NUMBER="24.02"
+export RAPIDS_DOCS_DIR="$(mktemp -d)"
+
+rapids-logger "Build CPP docs"
+pushd cpp/doxygen
+doxygen Doxyfile
+mkdir -p "${RAPIDS_DOCS_DIR}/libucxx/html"
+mv html/* "${RAPIDS_DOCS_DIR}/libucxx/html"
+popd
+
+rapids-upload-docs

ci/checks/doxygen.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Copyright (c) 2022-2024, NVIDIA CORPORATION.
+###############################
+# UCXX doxygen warnings check #
+###############################
+
+# skip if doxygen is not installed
+if ! [ -x "$(command -v doxygen)" ]; then
+  echo -e "warning: doxygen is not installed"
+  exit 0
+fi
+
+# Utility to return version as number for comparison
+function version { echo "$@" | awk -F. '{ printf("%d%03d%03d%03d\n", $1,$2,$3,$4); }'; }
+
+# doxygen supported version 1.10.0
+DOXYGEN_VERSION=`doxygen --version`
+if [ ! $(version "$DOXYGEN_VERSION") -eq $(version "1.10.0") ] ; then
+  echo -e "warning: Unsupported doxygen version $DOXYGEN_VERSION"
+  echo -e "Expecting doxygen version 1.10.0"
+  exit 0
+fi
+
+# Run doxygen, ignore missing tag files error
+TAG_ERROR1="error: Tag file '.*.tag' does not exist or is not a file. Skipping it..."
+TAG_ERROR2="error: cannot open tag file .*.tag for writing"
+DOXYGEN_STDERR=`cd cpp/doxygen && { cat Doxyfile ; echo QUIET = YES; echo GENERATE_HTML = NO; }  | doxygen - 2>&1 | sed "/\($TAG_ERROR1\|$TAG_ERROR2\)/d"`
+RETVAL=$?
+
+if [ "$RETVAL" != "0" ] || [ ! -z "$DOXYGEN_STDERR" ]; then
+  echo -e "$DOXYGEN_STDERR"
+  RETVAL=1 #because return value is not generated by doxygen 1.8.20
+fi
+
+exit $RETVAL

ci/release/update-version.sh

@@ -45,6 +45,9 @@ sed_runner "s/^version = .*/version = \"${NEXT_FULL_TAG}\"/g" python/distributed
 sed_runner "/- librmm =/ s/=.*/=${NEXT_RAPIDS_VERSION}/g" conda/recipes/ucxx/meta.yaml
 sed_runner "/- rmm =/ s/=.*/=${NEXT_RAPIDS_VERSION}/g" conda/recipes/ucxx/meta.yaml
 
+# doxyfile update
+sed_runner 's/PROJECT_NUMBER         = .*/PROJECT_NUMBER         = '${NEXT_FULL_TAG}'/g' cpp/doxygen/Doxyfile
+
 DEPENDENCIES=(
   cudf
   dask-cuda
@@ -65,3 +68,4 @@ sed_runner 's/'"branch-.*\/RAPIDS.cmake"'/'"branch-${NEXT_RAPIDS_VERSION}\/RAPID
 for FILE in .github/workflows/*.yaml; do
   sed_runner "/shared-workflows/ s/@.*/@branch-${NEXT_RAPIDS_VERSION}/g" "${FILE}"
 done
+sed_runner "s/RAPIDS_VERSION_NUMBER=\".*/RAPIDS_VERSION_NUMBER=\"${NEXT_SHORT_TAG}\"/g" ci/build_docs.sh

conda/environments/all_cuda-118_arch-x86_64.yaml

@@ -22,6 +22,7 @@ dependencies:
 - dask-cuda==24.2.*
 - dask-cudf==24.2.*
 - distributed
+- doxygen=1.10.0
 - fmt>=10.1.1,<11
 - gmock>=1.13.0
 - gtest>=1.13.0

conda/environments/all_cuda-120_arch-x86_64.yaml

@@ -22,6 +22,7 @@ dependencies:
 - dask-cuda==24.2.*
 - dask-cudf==24.2.*
 - distributed
+- doxygen=1.10.0
 - fmt>=10.1.1,<11
 - gmock>=1.13.0
 - gtest>=1.13.0