Migrate documentation to Fern platform

.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: "cpu-amd64-latest-4"
       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

@@ -433,10 +433,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: "cpu-amd64-latest-4"
       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/

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)

README.md

@@ -26,6 +26,61 @@ 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
+
+Documentation sources live in `fern/` — MDX pages edited directly and published via [Fern](https://buildwithfern.com).
+
+### Prerequisites
+
+| Tool | Install |
+|---|---|
+| Node.js + npm | `conda install nodejs` or [nodejs.org](https://nodejs.org/) |
+| jq | `sudo apt-get install jq` or `conda install jq` |
+
+The Fern CLI (`fern-api`) is installed automatically by `build.sh` at the version pinned in `fern/fern.config.json`.
+
+### Log in for local preview (first time only)
+
+The docs use `global-theme: nvidia`, which requires a Fern account authorized for the NVIDIA organization. Run this once:
+
+```bash
+fern login --email <your-nvidia-email>
+```
+
+### Build and preview locally
+
+```bash
+./build.sh docs
+```
+
+This runs the RST → MDX conversion, validates with `fern check`, then starts a live preview server at **http://localhost:3000** (Ctrl+C to stop).
+
+### Publish to the live site
+
+Publishing is handled automatically by CI on every push to `docs-fern-migration`.
+To publish manually (requires `FERN_TOKEN`):
+
+```bash
+FERN_TOKEN=<your-token> ./build.sh docs --publish-docs
+```
+
+**Getting `FERN_TOKEN`**: Ping `@aschilling`, `@dkoperda`, `@llane`, `@mmckiernan`, or `@nmckimpson` in the NVIDIA internal `#cdd-fern` Slack channel. Add the token as a `FERN_TOKEN` GitHub Actions secret in the repository settings.
+
+The live site is at **https://nvidia-cuopt.docs.buildwithfern.com**. Before going to production, a custom domain (`docs.nvidia.com/cuopt`) must be configured by the Fern team with Akamai fronting — contact `#cdd-fern` when ready.
+
+### How CI works
+
+| Trigger | What happens |
+|---|---|
+| Any push / PR touching `docs/`, `fern/`, or `python/cuopt/` | RST → MDX conversion + `fern check` + internal link check + external URL check |
+| Pull request (stage 1, no secrets) | Converts RST → MDX, uploads `fern/` as artifact |
+| Pull request (stage 2, secrets safe) | Publishes Fern preview, posts URL as PR comment |
+| Push to `docs-fern-migration` | Publishes to the live site via `fern generate --docs` |
+
+PR preview uses a two-stage workflow so that `FERN_TOKEN` is never exposed to fork PRs. Stage 2 runs in the base-branch context via `workflow_run`, where repository secrets are accessible.
+
+CI workflow: [`.github/workflows/fern-docs.yml`](.github/workflows/fern-docs.yml)
+
 ## 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 -h --help"
 HELP="$0 [<target> ...] [<flag> ...]
  where <target> is:
    clean            - remove all existing build artifacts and configuration (start over)
@@ -24,7 +24,9 @@ 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 Fern cloud instead
    deb              - build deb package (requires libcuopt to be built first)
  and <flag> is:
    -v               - verbose build mode
@@ -433,12 +435,55 @@ 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}"
 
-    cd "${REPODIR}"/docs/cuopt
-    make clean
-    make html linkcheck
+    if ! command -v node &>/dev/null || ! command -v npm &>/dev/null; then
+        echo "ERROR: Node.js (with npm) is required for the Fern CLI."
+        echo "       Install from: https://nodejs.org/  (or: conda install nodejs)"
+        exit 1
+    fi
+    if ! command -v jq &>/dev/null; then
+        echo "ERROR: jq is required to read the Fern version pin."
+        echo "       Install: sudo apt-get install jq"
+        exit 1
+    fi
+
+    # Install Fern CLI at the version pinned in fern/fern.config.json
+    FERN_VERSION=$(jq -r .version "${REPODIR}/fern/fern.config.json")
+    if ! fern --version 2>/dev/null | grep -q "${FERN_VERSION}"; then
+        echo "Installing fern-api@${FERN_VERSION}..."
+        npm install -g "fern-api@${FERN_VERSION}"
+    fi
+
+    # Regenerate dynamic API reference pages (OpenAPI spec, Python API, C API).
+    # In CI these packages come from conda; locally install them if missing.
+    PY=${PYTHON:-python3}
+    if command -v "${PY}" &>/dev/null; then
+        if ! "${PY}" -c "import fastapi, pydantic, yaml" 2>/dev/null; then
+            pip install --quiet -r "${REPODIR}/fern/requirements-docs.txt"
+        fi
+        "${PY}" "${REPODIR}/fern/generate_api_docs.py"
+    else
+        echo "  [WARN] Python not found; skipping API doc generation."
+    fi
+
+    echo "Running fern check..."
+    fern check
+
+    if hasArg --publish-docs; then
+        if [[ -z "${FERN_TOKEN}" ]]; then
+            echo "ERROR: FERN_TOKEN environment variable is not set."
+            echo "       Set it to your Fern token before running with --publish-docs."
+            exit 1
+        fi
+        echo "Publishing to Fern cloud..."
+        fern generate --docs
+        echo "Docs published to https://nvidia-cuopt.docs.buildwithfern.com"
+    else
+        echo ""
+        echo "Starting local preview at http://localhost:3000 (Ctrl+C to stop)..."
+        fern docs dev
+    fi
 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,20 @@ conda activate docs
 
 rapids-print-env
 
-rapids-logger "Build Docs"
-./build.sh docs
+rapids-logger "Install Fern CLI"
+FERN_VERSION=$(jq -r .version fern/fern.config.json)
+npm install -g "fern-api@${FERN_VERSION}"
+
+rapids-logger "Generate dynamic API docs (OpenAPI spec, Python API, C API)"
+python fern/generate_api_docs.py
+
+rapids-logger "Validate docs (fern check)"
+fern check
+
+if [[ "${RAPIDS_BUILD_TYPE:-branch}" == "pull-request" ]]; then
+    rapids-logger "Publishing Fern preview for PR review"
+    fern generate --docs --preview
+else
+    rapids-logger "Publishing Fern docs to production"
+    fern generate --docs
+fi

dependencies.yaml

@@ -786,26 +786,13 @@ dependencies:
     common:
       - output_types: [conda]
         packages:
+          - jq
+          - nodejs        # provides npm; used to install fern-api CLI
+          - *pyyaml
           - *doxygen
-          - &ipython ipython
-          - *jsonref
-          - make
-          - *msgpack_python
-          - *msgpack_numpy
-          - myst-parser
+          - fastapi
           - numpydoc
-          - pyrsistent
-          - breathe
-          - sphinx
-          - sphinx-copybutton
-          - sphinx-markdown-tables
-          - sphinx_rtd_theme
-          - sphinxcontrib-openapi
-          - sphinxcontrib-websupport
-          - sphinx-design
-          - pip:
-            - swagger-plugin-for-sphinx
-            - nvidia-sphinx-theme
+          - pydantic
 
   notebooks:
     common:

fern/Doxyfile

@@ -0,0 +1,41 @@
+# Doxyfile for fern/extract_c_api.py
+# Processes the two cuOpt C API headers and outputs XML only.
+# Run from the repo root: doxygen fern/Doxyfile
+# XML is written to fern/.doxygen-xml/ (git-ignored).
+
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = "cuOpt C API"
+PROJECT_BRIEF          = "NVIDIA cuOpt C API reference"
+OUTPUT_DIRECTORY       = fern/.doxygen-xml
+CREATE_SUBDIRS         = NO
+OUTPUT_LANGUAGE        = English
+FULL_PATH_NAMES        = NO
+MARKDOWN_SUPPORT       = YES
+EXTENSION_MAPPING      = h=C
+OPTIMIZE_OUTPUT_FOR_C  = YES
+
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = NO
+
+INPUT                  = cpp/include/cuopt/mathematical_optimization/cuopt_c.h \
+                         cpp/include/cuopt/mathematical_optimization/constants.h
+
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = *.h
+RECURSIVE              = NO
+
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = NO
+SKIP_FUNCTION_MACROS   = YES
+
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = NO
+
+QUIET                  = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = NO