docs(fern): custom Python/C API doc generator

.coderabbit.yaml

@@ -59,7 +59,7 @@ reviews:
         - Consistency: version numbers, parameter types, and terminology match code
         - Missing docs: if the PR changes public APIs without updating docs, flag as HIGH
 
-        When code changes affect docs, suggest specific files (e.g. docs/cuopt/source/*.rst)
+        When code changes affect docs, suggest specific files (e.g. fern/docs/pages/**/*.mdx)
         and recommend documenting performance characteristics, GPU requirements, or tolerances.
 
     - path: "cpp/include/cuopt/**/*"

.github/workflows/build.yaml

@@ -221,13 +221,11 @@ jobs:
     uses: rapidsai/shared-workflows/.github/workflows/custom-job.yaml@main
     with:
       build_type: ${{ inputs.build_type || 'branch' }}
-      node_type: "gpu-l4-latest-1"
+      node_type: "cpu4"
       sha: ${{ inputs.sha }}
       branch: ${{ inputs.branch }}
       date: ${{ inputs.date }}
       arch: "amd64"
-      file_to_upload: "docs/cuopt/build/html/"
-      artifact-name: "cuopt_docs"
       container_image: "rapidsai/ci-conda:26.08-latest"
       script: "ci/build_docs.sh"
   wheel-build-cuopt-sh-client:

.github/workflows/pr.yaml

@@ -71,7 +71,9 @@ jobs:
           - '**'
           - '!.ai/**'
           - '!.clang-format'
+          - '!.claude-plugin/**'
           - '!.coderabbit.yaml'
+          - '!.cursor-plugin/**'
           - '!.gitattributes'
           - '!.github/.ai/**'
           - '!.github/.coderabbit_review_guide.md'
@@ -104,6 +106,7 @@ jobs:
           - '!LICENSE'
           - '!README.md'
           - '!SECURITY.md'
+          - '!agents/**'
           - '!ci/build_wheel*.sh'
           - '!ci/check_style.sh'
           - '!ci/docker/**'
@@ -116,9 +119,17 @@ jobs:
           - '!ci/test_self_hosted_service.sh'
           - '!ci/test_wheel*.sh'
           - '!ci/thirdparty-testing/**'
+          - '!ci/utils/sync_skills_version.sh'
+          - '!ci/utils/validate_skills.sh'
+          - '!conda/**'
           - '!container-builder/**'
+          - '!datasets/**'
+          - '!gemini-extension.json'
           - '!helmchart/**'
+          - '!img/**'
           - '!ngc/**'
+          - '!notebooks/**'
+          - '!skills/**'
           - '!sonar-project.properties'
           - '!sonarqube/**'
           - '!ucf/**'
@@ -176,7 +187,7 @@ jobs:
           - '!ci/utils/sync_skills_version.sh'
           - '!ci/utils/validate_skills.sh'
           - '!container-builder/**'
-          - '!docs/**'
+          - '!fern/**'
           - '!gemini-extension.json'
           - '!helmchart/**'
           - '!img/**'
@@ -244,7 +255,7 @@ jobs:
           - '!ci/utils/sync_skills_version.sh'
           - '!ci/utils/validate_skills.sh'
           - '!container-builder/**'
-          - '!docs/**'
+          - '!fern/**'
           - '!gemini-extension.json'
           - '!helmchart/**'
           - '!img/**'
@@ -432,10 +443,8 @@ jobs:
     if: fromJSON(needs.changed-files.outputs.changed_file_groups).build_docs
     with:
       build_type: pull-request
-      node_type: "gpu-l4-latest-1"
+      node_type: "cpu4"
       arch: "amd64"
-      file_to_upload: "docs/cuopt/build/html/"
-      artifact-name: "cuopt_docs"
       container_image: "rapidsai/ci-conda:26.08-latest"
       script: "ci/build_docs.sh"
   wheel-build-libcuopt:

.gitignore

@@ -45,6 +45,7 @@ datasets/**
 ## Doxygen
 cpp/doxygen/html
 cpp/doxygen/xml
+fern/.doxygen-xml/
 
 # Jupyter Notebooks
 .ipynb_checkpoints
@@ -80,3 +81,4 @@ cpp/include/cuopt/semantic_version.hpp
 
 # conda env (recommended name)
 .cuopt_env
+cpp/build_split/

.pre-commit-config.yaml

@@ -41,6 +41,7 @@ repos:
             cpp|
             conda|
             docs|
+            fern|
             notebooks
           )
   - repo: https://github.com/pre-commit/mirrors-clang-format
@@ -100,24 +101,29 @@ repos:
             ^docs/cuopt/source/cuopt-server/nim-operator/guide/|
             (^|/)VERSION$|
             (^|/)RAPIDS_BRANCH$|
-            [.](md|rst|avro|parquet|png|orc|gz|pkl|sas7bdat|msgpack|pickle|jpg|bz2|zlib)$|
-            ^docs/cuopt/source/cuopt-python/routing/routing-example[.]ipynb$|
-            ^docs/cuopt/source/versions1[.]json$|
+            [.](md|mdx|rst|avro|parquet|png|orc|gz|pkl|sas7bdat|msgpack|pickle|jpg|bz2|zlib)$|
+
             ^helmchart/cuopt-server/(Chart[.]yaml|values[.]yaml)$|
             ^[.]cursor-plugin/plugin[.]json$|
             ^[.]claude-plugin/marketplace[.]json$|
-            ^gemini-extension[.]json$
+            ^gemini-extension[.]json$|
+            ^fern/docs[.]yml$|
+            ^fern/docs-v[0-9].*[.]yml$|
+            ^fern/openapi/cuopt_spec[.]yaml$|
+            ^fern/docs/scripts/cuopt-install-version[.]js$|
+            ^fern/docs/pages/cuopt-server/nim-operator/guide/
   - repo: https://github.com/zizmorcore/zizmor-pre-commit
     rev: v1.24.1
     hooks:
       - id: zizmor
   - repo: local
     hooks:
-      - id: update-versions
-        name: Update versions1.json
-        entry: python ci/utils/update_doc_versions.py
+      - id: update-fern-install-version
+        name: Update Fern install version script
+        entry: python ci/utils/update_fern_install_version.py
         language: system
-        files: docs/cuopt/source/versions1.json
+        pass_filenames: false
+        files: ^VERSION$
       - id: sync-skills-version
         name: Sync skills version from VERSION
         entry: ci/utils/sync_skills_version.sh

AGENTS.md

@@ -8,7 +8,7 @@ AI agent skills for NVIDIA cuOpt optimization engine. Skills live in **`skills/`
 
 ### Rules
 - `skills/cuopt-user-rules/` — Base rules for end users calling cuOpt (routing, LP, MILP, QP, install, server). Not for cuOpt internals — see `skills/cuopt-developer/`. Read first for user-facing tasks; choose skills from the index below by task and interface.
-- `skills/cuopt-developer/` — Modify, build, test, debug, and contribute to cuOpt internals (C++/CUDA, Python, server, CI). Use for solver internals, PRs, DCO, and code conventions. For **VRP dimension** work (combine invariants, fwd/bwd propagation, new constraints/objectives in the routing engine), read **`skills/cuopt-developer/references/vrp_skills.md`** in addition to `SKILL.md`.
+- `skills/cuopt-developer/` — Modify, build, test, debug, and contribute to cuOpt internals (C++/CUDA, Python, server, CI). Use for solver internals, PRs, DCO, and code conventions. **Also read for any CI or workflow change** (new jobs, new scripts, dependency additions) — the existing pipeline in `ci/`, `pr.yaml`, and `build.yaml` must be understood before adding anything new. **Before writing a custom script to extract, parse, or transform content, check whether an established tool already exists** (e.g. numpydoc for Python docstrings, Doxygen for C/C++ headers, pandoc for markup conversion) — custom parsers are a last resort. For **VRP dimension** work (combine invariants, fwd/bwd propagation, new constraints/objectives in the routing engine), read **`skills/cuopt-developer/references/vrp_skills.md`** in addition to `SKILL.md`.
 - `skills/cuopt-skill-evolution/` — Skill evolution: after solving a non-trivial problem, propose skill updates to capture generalizable learnings.
 
 ### Common (concepts only; no API code)

CONTRIBUTING.md

@@ -241,13 +241,9 @@ pytest -v ${CUOPT_HOME}/python/cuopt/cuopt/tests
 ## gRPC Remote Execution
 
 NVIDIA cuOpt includes a gRPC-based remote execution system for running solves on a
-GPU server from a program using the API locally. User documentation lives under `docs/cuopt/source/cuopt-grpc/` (Sphinx **gRPC remote execution** section):
-
-- `quick-start.rst` — Install/Docker/selector, how remote execution works, minimal LP and CLI examples (default C bundle).
-- `advanced.rst` — TLS, tuning, limitations, troubleshooting.
-- `examples.rst`, `api.rst` — Sample patterns and RPC overview.
-- `docs/cuopt/source/cuopt-grpc/grpc-server-architecture.md` — Short **gRPC server behavior** page in user docs.
-- `cpp/docs/grpc-server-architecture.md` — Full contributor reference (IPC, C++ source map, streaming).
+GPU server from a program using the API locally. User documentation for gRPC lives in
+`fern/docs/pages/cuopt-grpc/`. The contributor reference for the gRPC server internals
+is at `cpp/docs/grpc-server-architecture.md`.
 
 ## Debugging cuOpt
 

README.md

@@ -26,6 +26,10 @@ For the latest version, ensure you are on the `main` branch.
 
 [cuOpt Documentation](https://docs.nvidia.com/cuopt/user-guide/latest/introduction.html)
 
+## Contributing to the Documentation
+
+See [`fern/README.md`](fern/README.md) for how to edit pages, add API symbols or examples, and run a local preview.
+
 ## Supported APIs
 
 cuOpt supports the following APIs:

build.sh

@@ -14,7 +14,7 @@ ARGS=$*
 REPODIR=$(cd "$(dirname "$0")"; pwd)
 LIBCUOPT_BUILD_DIR=${LIBCUOPT_BUILD_DIR:=${REPODIR}/cpp/build}
 
-VALIDARGS="clean codegen libcuopt cuopt_grpc_server cuopt cuopt_server cuopt_sh_client docs deb -a -b -g -fsanitize -tsan -msan -v -l= --verbose-pdlp --build-lp-only  --no-fetch-rapids --skip-c-python-adapters --skip-tests-build --skip-routing-build --skip-grpc-build --skip-fatbin-write --host-lineinfo [--cmake-args=\\\"<args>\\\"] [--cache-tool=<tool>] -n --allgpuarch --ci-only-arch --show_depr_warn -h --help"
+VALIDARGS="clean codegen libcuopt cuopt_grpc_server cuopt cuopt_server cuopt_sh_client docs deb -a -b -g -fsanitize -tsan -msan -v -l= --verbose-pdlp --build-lp-only  --no-fetch-rapids --skip-c-python-adapters --skip-tests-build --skip-routing-build --skip-grpc-build --skip-fatbin-write --host-lineinfo [--cmake-args=\\\"<args>\\\"] [--cache-tool=<tool>] -n --allgpuarch --ci-only-arch --show_depr_warn --publish-docs --preview -h --help"
 HELP="$0 [<target> ...] [<flag> ...]
  where <target> is:
    clean            - remove all existing build artifacts and configuration (start over)
@@ -24,7 +24,10 @@ HELP="$0 [<target> ...] [<flag> ...]
    cuopt            - build the cuopt Python package
    cuopt_server     - build the cuopt_server Python package
    cuopt_sh_client  - build cuopt self host client
-   docs             - build the docs
+   docs             - build the Fern docs (generate MDX + validate); starts local
+                      preview server at http://localhost:3000 when done.
+                      Pass --publish-docs to publish to production, or
+                      --preview for a CI PR preview build
    deb              - build deb package (requires libcuopt to be built first)
  and <flag> is:
    -v               - verbose build mode
@@ -63,8 +66,7 @@ PY_LIBCUOPT_BUILD_DIR=${REPODIR}/python/libcuopt/build
 CUOPT_BUILD_DIR=${REPODIR}/python/cuopt/build
 CUOPT_SERVER_BUILD_DIR=${REPODIR}/python/cuopt_server/build
 CUOPT_SH_CLIENT_BUILD_DIR=${REPODIR}/python/cuopt_self_hosted/build
-DOCS_BUILD_DIR=${REPODIR}/docs/cuopt/build
-BUILD_DIRS="${LIBCUOPT_BUILD_DIR} ${CUOPT_BUILD_DIR} ${CUOPT_SERVER_BUILD_DIR} ${CUOPT_SERVICE_CLIENT_BUILD_DIR} ${CUOPT_SH_CLIENT_BUILD_DIR} ${PY_LIBCUOPT_BUILD_DIR} ${DOCS_BUILD_DIR}"
+BUILD_DIRS="${LIBCUOPT_BUILD_DIR} ${CUOPT_BUILD_DIR} ${CUOPT_SERVER_BUILD_DIR} ${CUOPT_SERVICE_CLIENT_BUILD_DIR} ${CUOPT_SH_CLIENT_BUILD_DIR} ${PY_LIBCUOPT_BUILD_DIR}"
 
 # Set defaults for vars modified by flags to this script
 VERBOSE_FLAG=""
@@ -433,12 +435,10 @@ if buildAll || hasArg cuopt_sh_client; then
     python "${PYTHON_ARGS_FOR_INSTALL[@]}" .
 fi
 
-# Build the docs (opt-in; pass 'docs' explicitly to build)
+# Build the Fern docs (opt-in; pass 'docs' explicitly to build)
 if hasArg docs; then
-    cd "${REPODIR}"/cpp/doxygen
-    doxygen Doxyfile
-
-    cd "${REPODIR}"/docs/cuopt
-    make clean
-    make html linkcheck
+    DOCS_FLAG=""
+    hasArg --publish-docs && DOCS_FLAG="--publish-docs"
+    hasArg --preview && DOCS_FLAG="--preview"
+    bash "${REPODIR}/fern/build_docs.sh" ${DOCS_FLAG}
 fi

ci/build_docs.sh

@@ -5,7 +5,7 @@
 
 set -euo pipefail
 
-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"
@@ -21,7 +21,6 @@ CPP_CHANNEL=$(rapids-download-from-github "$(rapids-artifact-name conda_cpp libc
 PYTHON_CHANNEL=$(rapids-download-from-github "$(rapids-artifact-name conda_python cuopt cuopt --py "$RAPIDS_PY_VERSION" --cuda "$RAPIDS_CUDA_VERSION")")
 
 rapids-logger "Generating conda environment YAML"
-
 rapids-dependency-file-generator \
   --output conda \
   --file-key docs \
@@ -34,5 +33,10 @@ conda activate docs
 
 rapids-print-env
 
-rapids-logger "Build Docs"
-./build.sh docs
+if [[ "${RAPIDS_BUILD_TYPE:-branch}" == "pull-request" ]]; then
+    rapids-logger "Building and publishing Fern PR preview"
+    ./build.sh docs --preview
+else
+    rapids-logger "Building and publishing Fern docs to production"
+    ./build.sh docs --publish-docs
+fi

ci/release/update-version.sh

@@ -117,11 +117,9 @@ for DEP in "${DEPENDENCIES[@]}"; do
   for FILE in python/*/pyproject.toml; do
     sed_runner "/\"${DEP}==/ s/==.*\"/==${NEXT_SHORT_TAG_PEP440}.*,>=0.0.0a0\"/g" "${FILE}"
   done
-  for FILE in docs/cuopt/source/*/quick-start.rst README.md; do
-    sed_runner "/${DEP}\(-cu[[:digit:]]\{2\}\)\{0,1\}==/ s/==[0-9]\+\.[0-9]\+\.\*/==${NEXT_SHORT_TAG_PEP440}.\*/g" "${FILE}"
-    sed_runner "/${DEP}=/ s/=[0-9]\+\.[0-9]\+\(\.[0-9]\+\)\?[^ ]*/=${NEXT_SHORT_TAG}.*/g" "${FILE}"
-    sed_runner "/${DEP}:/ s/:[0-9]\{2\}\.[0-9]\{1,2\}\.[0-9]\+\(-cuda[0-9]\+\.[0-9]\+-\)\(py[0-9]\+\)/:${DOCKER_TAG}\1\2/g" "${FILE}"
-  done
+  sed_runner "/${DEP}\(-cu[[:digit:]]\{2\}\)\{0,1\}==/ s/==[0-9]\+\.[0-9]\+\.\*/==${NEXT_SHORT_TAG_PEP440}.\*/g" README.md
+  sed_runner "/${DEP}=/ s/=[0-9]\+\.[0-9]\+\(\.[0-9]\+\)\?[^ ]*/=${NEXT_SHORT_TAG}.*/g" README.md
+  sed_runner "/${DEP}:/ s/:[0-9]\{2\}\.[0-9]\{1,2\}\.[0-9]\+\(-cuda[0-9]\+\.[0-9]\+-\)\(py[0-9]\+\)/:${DOCKER_TAG}\1\2/g" README.md
 done
 
 # Update README.md version badge
@@ -135,22 +133,14 @@ sed_runner 's/\(tag: "\)[0-9][0-9]\.[0-9]\+\.[0-9]\+\(-cuda12\.9-py3\.12"\)/\1'$
 sed_runner 's/\(appVersion: \)[0-9][0-9]\.[0-9]\+\.[0-9]\+/\1'${DOCKER_TAG}'/g' helmchart/cuopt-server/Chart.yaml
 sed_runner 's/\(version: \)[0-9][0-9]\.[0-9]\+\.[0-9]\+/\1'${DOCKER_TAG}'/g' helmchart/cuopt-server/Chart.yaml
 
+# Update Fern docs version switcher and install widget
+python ci/utils/update_fern_versions.py
+python ci/utils/update_fern_install_version.py
+
 # CI files - context-aware branch references and version updates
 for FILE in .github/workflows/*.yaml; do
   sed_runner "/shared-workflows/ s|@.*|@${RAPIDS_BRANCH_NAME}|g" "${FILE}"
   # CI image tags of the form rapidsai/<image>:{rapids_version}-{something}.
   # Scoped to rapidsai/ so unrelated images like python:3.14-slim aren't rewritten.
   sed_runner "/rapidsai\// s|:[0-9]*\\.[0-9]*-|:${NEXT_SHORT_TAG}-|g" "${FILE}"
 done
-
-# Documentation references - context-aware
-if [[ "${RUN_CONTEXT}" == "main" ]]; then
-  # In main context, keep external documentation on main (no changes needed)
-  :
-elif [[ "${RUN_CONTEXT}" == "release" ]]; then
-  # In release context, use release branch for external documentation links (word boundaries to avoid partial matches)
-  sed_runner "s|\\bmain\\b|release/${NEXT_SHORT_TAG}|g" docs/cuopt/source/faq.rst
-fi
-
-# Update docs version switcher to include the new version
-python ci/utils/update_doc_versions.py

ci/test_doc_examples.sh

@@ -25,7 +25,7 @@ SKIPPED_TESTS=0
 # Directory setup
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
-DOCS_ROOT="${PROJECT_ROOT}/docs/cuopt/source"
+DOCS_ROOT="${PROJECT_ROOT}/fern/docs/pages"
 RESULTS_DIR="${PROJECT_ROOT}/test-results"
 SERVER_PID=""
 

ci/test_wheel_cuopt_server.sh

@@ -50,7 +50,7 @@ timeout 30m ./ci/run_cuopt_server_pytests.sh \
   --junitxml="${RAPIDS_TESTS_DIR}/junit-wheel-cuopt-server.xml" \
   --verbose --capture=no || FAILED_STEPS+=("pytest cuopt-server (wheel)")
 
-# Run documentation tests
+# Run documentation examples
 ./ci/test_doc_examples.sh || FAILED_STEPS+=("doc examples")
 
 # Generate nightly test report