[Docs] Convert Sphinx docs to Fern (#2067)

This PR converts the current Sphinx docs to Fern in preparation for the move to docs.nvidia.com. Instead of manually composing the API reference docs, this PR also generates API reference docs for all supported languages directly from the code (as is standard in Fern). 

There's a lot of files in this PR, and most of the markdown files are either copied over to the Fern directory format from the old Sphinx docs, or they've been auto-generated using the new API reference docs generation scripts (`generate_api_reference.py` in the changes). When reviewing this PR, it's probably better to start with the non-markdown files, then build the docs and run them locally. 

The docs can be built in the usual way with `./build.sh docs`. You can run them locally using the following command:

```
fern/build_docs.sh dev --port 3000 --backend-port 3001
```

Authors:
  - Corey J. Nolet (https://github.com/cjnolet)

Approvers:
  - Bradley Dice (https://github.com/bdice)
  - Divye Gala (https://github.com/divyegala)
  - Robert Maynard (https://github.com/robertmaynard)

URL: #2067

Author: cjnolet

.github/CODEOWNERS

@@ -20,6 +20,7 @@ examples/rust/     @rapidsai/cuvs-rust-codeowners
 
 #docs code owners
 docs/              @rapidsai/cuvs-docs-codeowners
+fern/              @rapidsai/cuvs-docs-codeowners
 
 #cmake code owners
 CMakeLists.txt                  @rapidsai/cuvs-cmake-codeowners

.github/workflows/build.yaml

@@ -229,7 +229,6 @@ jobs:
     uses: ./.github/workflows/publish-rust.yaml
   docs-build:
     if: github.ref_type == 'branch'
-    needs: python-build
     permissions:
       actions: read
       contents: read

.github/workflows/check-c-abi.yaml

@@ -128,5 +128,5 @@ jobs:
                    - The changes are documented in the changelog
                    - Migration guide is provided for users
 
-                For more information, see the [C ABI documentation](../docs/source/c_developer_guide.md).`
+                For more information, see the [C API documentation](../fern/pages/c_api/index.md).`
             });

.github/workflows/pr.yaml

@@ -134,6 +134,7 @@ jobs:
           - '!ci/test_wheel_cuvs.sh'
           - '!ci/validate_wheel.sh'
           - '!docs/**'
+          - '!fern/**'
           - '!go/**'
           - '!img/**'
           - '!java/**'
@@ -170,6 +171,7 @@ jobs:
           - '!ci/validate_wheel.sh'
           - '!Dockerfile'
           - '!docs/**'
+          - '!fern/**'
           - '!img/**'
           - '!notebooks/**'
           - '!python/**'
@@ -209,6 +211,7 @@ jobs:
           - '!Dockerfile'
           - '!README.md'
           - '!docs/**'
+          - '!fern/**'
           - '!go/**'
           - '!img/**'
           - '!java/**'
@@ -253,6 +256,7 @@ jobs:
           - '!cpp/.clang-tidy'
           - '!cpp/doxygen/**'
           - '!docs/**'
+          - '!fern/**'
           - '!java/**'
           - '!go/**'
           - '!img/**'
@@ -292,6 +296,7 @@ jobs:
           - '!ci/test_wheel_cuvs.sh'
           - '!ci/validate_wheel.sh'
           - '!docs/**'
+          - '!fern/**'
           - '!go/**'
           - '!img/**'
           - '!java/**'
@@ -332,6 +337,7 @@ jobs:
           - '!ci/test_wheel_cuvs.sh'
           - '!ci/validate_wheel.sh'
           - '!docs/**'
+          - '!fern/**'
           - '!img/**'
           - '!java/**'
           - '!notebooks/**'
@@ -581,7 +587,6 @@ jobs:
       container_image: "rapidsai/ci-conda:26.06-cuda${{ matrix.CUDA_VER }}-${{ matrix.LINUX_VER }}-py${{ matrix.PY_VER }}"
       script: "ci/build_go.sh"
   docs-build:
-    needs: conda-python-build
     permissions:
       actions: read
       contents: read

build.sh

@@ -67,8 +67,7 @@ HELP="$0 [<target> ...] [<flag> ...] [--cmake-args=\"<args>\"] [--cache-tool=<to
  default action (no args) is to build libcuvs, tests and cuvs targets
 "
 LIBCUVS_BUILD_DIR=${LIBCUVS_BUILD_DIR:=${REPODIR}/cpp/build}
-SPHINX_BUILD_DIR=${REPODIR}/docs
-DOXYGEN_BUILD_DIR=${REPODIR}/cpp/doxygen
+FERN_DOCS_DIR=${REPODIR}/fern
 PYTHON_BUILD_DIR=${REPODIR}/python/cuvs/_skbuild
 RUST_BUILD_DIR=${REPODIR}/rust/target
 JAVA_BUILD_DIR=${REPODIR}/java/cuvs-java/target
@@ -99,7 +98,9 @@ EXTRA_CMAKE_ARGS=""
 
 # Set defaults for vars that may not have been defined externally
 INSTALL_PREFIX=${INSTALL_PREFIX:=${PREFIX:=${CONDA_PREFIX:=$LIBCUVS_BUILD_DIR/install}}}
-PARALLEL_LEVEL=${PARALLEL_LEVEL:=$(nproc)}
+if [[ -z "${PARALLEL_LEVEL:-}" ]]; then
+    PARALLEL_LEVEL=$(getconf _NPROCESSORS_ONLN 2>/dev/null || nproc)
+fi
 BUILD_ABI=${BUILD_ABI:=ON}
 
 # Default to Ninja if generator is not specified
@@ -371,7 +372,7 @@ fi
 
 ################################################################################
 # Configure for building all C++ targets
-if (( NUMARGS == 0 )) || hasArg libcuvs || hasArg docs || hasArg tests || hasArg bench-prims || hasArg bench-ann || hasArg examples; then
+if (( NUMARGS == 0 )) || hasArg libcuvs || hasArg tests || hasArg bench-prims || hasArg bench-ann || hasArg examples; then
     COMPILE_LIBRARY=ON
     if [[ "${BUILD_SHARED_LIBS}" != "OFF" ]]; then
         CMAKE_TARGET+=("cuvs")
@@ -535,13 +536,8 @@ export RAPIDS_VERSION_MAJOR_MINOR
 
 if hasArg docs; then
     set -x
-    cd "${DOXYGEN_BUILD_DIR}"
-    doxygen Doxyfile
-    cd "${SPHINX_BUILD_DIR}"
-    make html
-    cd "${REPODIR}"/rust
-    cargo doc -p cuvs --no-deps
-    rsync -av "${RUST_BUILD_DIR}"/doc/ "${SPHINX_BUILD_DIR}"/build/html/_static/rust
+    cd "${REPODIR}"
+    "${FERN_DOCS_DIR}/build_docs.sh" "${FERN_DOCS_MODE:-check}"
 fi
 
 ################################################################################

ci/build_docs.sh

@@ -4,25 +4,16 @@
 
 set -euo pipefail
 
-rapids-logger "Downloading artifacts from previous jobs"
-CPP_CHANNEL=$(rapids-download-conda-from-github cpp)
-PYTHON_CHANNEL=$(rapids-download-from-github "$(rapids-package-name "conda_python" cuvs --stable --cuda "$RAPIDS_CUDA_VERSION")")
-
-rapids-logger "Create test conda environment"
+rapids-logger "Create docs conda environment"
 . /opt/conda/etc/profile.d/conda.sh
 
 rapids-logger "Configuring conda strict channel priority"
 conda config --set channel_priority strict
 
-RAPIDS_VERSION_MAJOR_MINOR="$(rapids-version-major-minor)"
-export RAPIDS_VERSION_MAJOR_MINOR
-
 rapids-dependency-file-generator \
   --output conda \
   --file-key docs \
   --matrix "cuda=${RAPIDS_CUDA_VERSION%.*};arch=$(arch);py=${RAPIDS_PY_VERSION}" \
-  --prepend-channel "${CPP_CHANNEL}" \
-  --prepend-channel "${PYTHON_CHANNEL}" \
   | tee env.yaml
 
 rapids-mamba-retry env create --yes -f env.yaml -n docs
@@ -35,27 +26,40 @@ set -eu
 
 rapids-print-env
 
-RAPIDS_DOCS_DIR="$(mktemp -d)"
-export RAPIDS_DOCS_DIR
-
-rapids-logger "Build CPP docs"
-pushd cpp/doxygen
-doxygen Doxyfile
-popd
-
-rapids-logger "Build Rust docs"
-pushd rust
-LIBCLANG_PATH=$(dirname "$(find "$CONDA_PREFIX" -name libclang.so | head -n 1)")
-export LIBCLANG_PATH
-cargo doc -p cuvs --no-deps
-popd
-
-rapids-logger "Build Python docs"
-pushd docs
-make dirhtml
-mv ../rust/target/doc ./build/dirhtml/_static/rust
-mkdir -p "${RAPIDS_DOCS_DIR}/cuvs/"html
-mv build/dirhtml/* "${RAPIDS_DOCS_DIR}/cuvs/html"
-popd
-
-RAPIDS_VERSION_NUMBER="${RAPIDS_VERSION_MAJOR_MINOR}" rapids-upload-docs
+rapids-logger "Validate Fern docs"
+
+find_pr_number() {
+  local ref
+  for ref in "${RAPIDS_REF_NAME:-}" "${GITHUB_REF:-}" "${GITHUB_REF_NAME:-}"; do
+    if [[ "${ref}" =~ (^|/)pull-request/([0-9]+)$ ]]; then
+      echo "${BASH_REMATCH[2]}"
+      return 0
+    fi
+    if [[ "${ref}" =~ ^refs/pull/([0-9]+)/ ]]; then
+      echo "${BASH_REMATCH[1]}"
+      return 0
+    fi
+    if [[ "${ref}" =~ ^([0-9]+)/merge$ ]]; then
+      echo "${BASH_REMATCH[1]}"
+      return 0
+    fi
+  done
+}
+
+FERN_DOCS_MODE="${FERN_DOCS_MODE:-check}"
+FERN_DOCS_ARGS=()
+
+if [[ "${FERN_DOCS_MODE}" == "preview" ]]; then
+  FERN_PREVIEW_ID="${FERN_DOCS_PREVIEW_ID:-}"
+  if [[ -z "${FERN_PREVIEW_ID}" ]]; then
+    PR_NUMBER="$(find_pr_number || true)"
+    if [[ -n "${PR_NUMBER}" ]]; then
+      FERN_PREVIEW_ID="pr-${PR_NUMBER}"
+    fi
+  fi
+  if [[ -n "${FERN_PREVIEW_ID}" ]]; then
+    FERN_DOCS_ARGS+=(--id "${FERN_PREVIEW_ID}")
+  fi
+fi
+
+fern/build_docs.sh "${FERN_DOCS_MODE}" "${FERN_DOCS_ARGS[@]}"

ci/release/update-version.sh

@@ -139,14 +139,14 @@ if [[ "${RUN_CONTEXT}" == "main" ]]; then
   :
 elif [[ "${RUN_CONTEXT}" == "release" ]]; then
   # In release context, use release branch for documentation links (word boundaries to avoid partial matches)
-  sed_runner "/rapidsai\\/cuvs/ s|\\bmain\\b|release/${NEXT_SHORT_TAG}|g" docs/source/developer_guide.md
+  sed_runner "/rapidsai\\/cuvs/ s|\\bmain\\b|release/${NEXT_SHORT_TAG}|g" fern/pages/developer_guide.md
   sed_runner "s|\\bmain\\b|release/${NEXT_SHORT_TAG}|g" README.md
   # Only update the GitHub URL, not the main() function
   sed_runner "s|/cuvs/blob/\\bmain\\b/|/cuvs/blob/release/${NEXT_SHORT_TAG}/|g" python/cuvs_bench/cuvs_bench/plot/__main__.py
 fi
 
 # Update cuvs-bench Docker image references (version-only, not branch-related)
-sed_runner "s|rapidsai/cuvs-bench:[0-9][0-9].[0-9][0-9]|rapidsai/cuvs-bench:${NEXT_SHORT_TAG}|g" docs/source/cuvs_bench/index.rst
+sed_runner "s|rapidsai/cuvs-bench:[0-9][0-9].[0-9][0-9]|rapidsai/cuvs-bench:${NEXT_SHORT_TAG}|g" fern/pages/cuvs_bench/index.md
 
 # Version references (not branch-related)
 sed_runner "s|=[0-9][0-9].[0-9][0-9]|=${NEXT_SHORT_TAG}|g" README.md

conda/environments/all_cuda-129_arch-aarch64.yaml

@@ -6,7 +6,6 @@ channels:
 - conda-forge
 dependencies:
 - _go_select *=cgo
-- breathe>=4.35.0
 - c-compiler
 - clang-tools==20.1.8
 - clang==20.1.8
@@ -21,11 +20,8 @@ dependencies:
 - cxx-compiler
 - cython>=3.2.2
 - dlpack>=0.8,<1.0
-- doxygen>=1.8.20
 - gcc_linux-aarch64=14.*
 - go
-- graphviz
-- ipython
 - libclang==20.1.8
 - libcublas-dev
 - libcurand-dev
@@ -37,22 +33,16 @@ dependencies:
 - make
 - nccl>=2.19
 - ninja
+- nodejs>=22
 - numpy>=1.23,<3.0
-- numpydoc
 - openblas
 - pre-commit
 - pylibraft==26.6.*,>=0.0.0a0
 - pytest
 - pytest-cov
 - rapids-build-backend>=0.4.0,<0.5.0
-- recommonmark
 - rust
 - scikit-build-core>=0.11.0
 - scikit-learn>=1.5
-- sphinx-copybutton
-- sphinx-markdown-tables
-- sphinx>=8.0.0
 - sysroot_linux-aarch64==2.28
-- pip:
-  - nvidia-sphinx-theme
 name: all_cuda-129_arch-aarch64

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

@@ -6,7 +6,6 @@ channels:
 - conda-forge
 dependencies:
 - _go_select *=cgo
-- breathe>=4.35.0
 - c-compiler
 - clang-tools==20.1.8
 - clang==20.1.8
@@ -21,11 +20,8 @@ dependencies:
 - cxx-compiler
 - cython>=3.2.2
 - dlpack>=0.8,<1.0
-- doxygen>=1.8.20
 - gcc_linux-64=14.*
 - go
-- graphviz
-- ipython
 - libclang==20.1.8
 - libcublas-dev
 - libcurand-dev
@@ -36,22 +32,16 @@ dependencies:
 - make
 - nccl>=2.19
 - ninja
+- nodejs>=22
 - numpy>=1.23,<3.0
-- numpydoc
 - openblas
 - pre-commit
 - pylibraft==26.6.*,>=0.0.0a0
 - pytest
 - pytest-cov
 - rapids-build-backend>=0.4.0,<0.5.0
-- recommonmark
 - rust
 - scikit-build-core>=0.11.0
 - scikit-learn>=1.5
-- sphinx-copybutton
-- sphinx-markdown-tables
-- sphinx>=8.0.0
 - sysroot_linux-64==2.28
-- pip:
-  - nvidia-sphinx-theme
 name: all_cuda-129_arch-x86_64

conda/environments/all_cuda-132_arch-aarch64.yaml

@@ -6,7 +6,6 @@ channels:
 - conda-forge
 dependencies:
 - _go_select *=cgo
-- breathe>=4.35.0
 - c-compiler
 - clang-tools==20.1.8
 - clang==20.1.8
@@ -21,11 +20,8 @@ dependencies:
 - cxx-compiler
 - cython>=3.2.2
 - dlpack>=0.8,<1.0
-- doxygen>=1.8.20
 - gcc_linux-aarch64=14.*
 - go
-- graphviz
-- ipython
 - libclang==20.1.8
 - libcublas-dev
 - libcurand-dev
@@ -37,22 +33,16 @@ dependencies:
 - make
 - nccl>=2.19
 - ninja
+- nodejs>=22
 - numpy>=1.23,<3.0
-- numpydoc
 - openblas
 - pre-commit
 - pylibraft==26.6.*,>=0.0.0a0
 - pytest
 - pytest-cov
 - rapids-build-backend>=0.4.0,<0.5.0
-- recommonmark
 - rust
 - scikit-build-core>=0.11.0
 - scikit-learn>=1.5
-- sphinx-copybutton
-- sphinx-markdown-tables
-- sphinx>=8.0.0
 - sysroot_linux-aarch64==2.28
-- pip:
-  - nvidia-sphinx-theme
 name: all_cuda-132_arch-aarch64