Skip to content

Updating Fern and fixing a couple small links #2210

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rapids-bot merged 5 commits into from
Jun 4, 2026
Merged

Updating Fern and fixing a couple small links #2210

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
14a4b27
Update Fern and reorganize guide navigation
cjnolet Jun 2, 2026
8feffa0
Move integration patterns under field guide
cjnolet Jun 2, 2026
066d806
Update field guide docs
cjnolet Jun 2, 2026
6ff921e
Update fern/pages/advanced_topics.md
cjnolet Jun 2, 2026
729e9d2
Fix Fern API reference formatting
cjnolet Jun 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions fern/build_docs.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,8 +52,22 @@ require_node_22() {

require_node_22

fern_config_version() {
python3 - "${SCRIPT_DIR}/fern.config.json" <<'PY'
import json
import sys

with open(sys.argv[1], encoding="utf-8") as f:
print(json.load(f).get("version", "*"))
PY
}

FERN_VERSION="$(fern_config_version)"

if [[ -n "${FERN_CLI:-}" ]]; then
FERN_CMD=("${FERN_CLI}")
elif [[ "${FERN_VERSION}" != "*" ]]; then
FERN_CMD=("npx" "--yes" "fern-api@${FERN_VERSION}")
elif command -v fern >/dev/null 2>&1; then
FERN_CMD=("fern")
else
Expand Down
36 changes: 27 additions & 9 deletions fern/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,22 @@ redirects:
destination: "/cuvs/developer-guide/coding-guidelines/cpp-guidelines"
- source: "/cuvs/developer-guide/guidelines/python-guidelines"
destination: "/cuvs/developer-guide/coding-guidelines/python-guidelines"
- source: "/cuvs/user-guide/compatibility"
destination: "/cuvs/user-guide/field-guide/compatibility"
- source: "/cuvs/user-guide/integration-patterns"
destination: "/cuvs/user-guide/field-guide/integration-patterns"
- source: "/cuvs/user-guide/advanced-topics"
destination: "/cuvs/user-guide/field-guide"
- source: "/cuvs/user-guide/advanced-topics/jit-compilation"
destination: "/cuvs/user-guide/field-guide/jit-compilation"
- source: "/cuvs/user-guide/advanced-topics/udf-usage"
destination: "/cuvs/user-guide/field-guide/udf-usage"
- source: "/cuvs/developer-guide/advanced-topics/jit-compilation"
destination: "/cuvs/user-guide/field-guide/jit-compilation"
- source: "/cuvs/developer-guide/abi-stability"
destination: "/cuvs/developer-guide/advanced-topics/abi-stability"
- source: "/cuvs/developer-guide/link-time-optimization"
destination: "/cuvs/developer-guide/advanced-topics/link-time-optimization"
layout:
searchbar-placement: "header"
page-width: "1376px"
Expand Down Expand Up @@ -206,13 +222,13 @@ navigation:
- page: "Wiki-all Dataset"
hidden: true
path: "./pages/cuvs_bench/wiki_all_dataset.md"
- page: "Compatibility"
path: "./pages/user_guide/abi_stability.md"
- page: "Integration Patterns"
path: "./pages/user_guide/integration_patterns.md"
- section: "Advanced Topics"
- section: "Field Guide"
path: "./pages/advanced_topics.md"
contents:
- page: "Compatibility"
path: "./pages/user_guide/abi_stability.md"
- page: "Integration Patterns"
path: "./pages/user_guide/integration_patterns.md"
- page: "JIT Compilation"
path: "./pages/jit_compilation.md"
- page: "UDF Usage"
Expand All @@ -233,10 +249,12 @@ navigation:
path: "./pages/java_guidelines.md"
- page: "Python Guidelines"
path: "./pages/python_guidelines.md"
- page: "ABI Stability"
path: "./developer_guide/abi_stability.md"
- page: "Link-time Optimization"
path: "./pages/jit_lto_guide.md"
- section: "Advanced Topics"
contents:
- page: "ABI Stability"
path: "./developer_guide/abi_stability.md"
- page: "Link-time Optimization"
Comment on lines +254 to +256

@coderabbitai coderabbitai Bot Jun 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Fix broken navigation path for ABI Stability.

Line 253 uses ./developer_guide/abi_stability.md, but navigation paths in this file consistently resolve from ./pages/.... This likely breaks the Developer Guide sidebar entry and link checks.

Suggested fix 
       - section: "Advanced Topics"
         contents:
           - page: "ABI Stability"
-            path: "./developer_guide/abi_stability.md"
+            path: "./pages/developer_guide/abi_stability.md"
           - page: "Link-time Optimization"
             path: "./pages/jit_lto_guide.md"
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- page: "ABI Stability"
path: "./developer_guide/abi_stability.md"
- page: "Link-time Optimization"
- page: "ABI Stability"
path: "./pages/developer_guide/abi_stability.md"
- page: "Link-time Optimization"
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@fern/docs.yml` around lines 252 - 254, The "ABI Stability" navigation entry
uses a relative path "./developer_guide/abi_stability.md" that is inconsistent
with other entries; update the path for the page "ABI Stability" (the YAML
mapping with key page: "ABI Stability") to match the repository's nav convention
(e.g. "./pages/developer_guide/abi_stability.md") so sidebar resolution and link
checks succeed.

path: "./pages/jit_lto_guide.md"
- page: "Contributing"
path: "./pages/contributing.md"
- section: "API Reference"
Expand Down
2 changes: 1 addition & 1 deletion fern/fern.config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{
"organization": "nvidia",
"version": "*"
"version": "5.44.3"
}
13 changes: 7 additions & 6 deletions fern/pages/advanced_topics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
---
slug: user-guide/advanced-topics
slug: user-guide/field-guide
---

# Advanced Topics
# Field Guide

Use these pages when working on specialized NVIDIA cuVS development topics that need lower-level implementation context, runtime behavior, or platform-specific guidance.
The Field Guide collects practical material for users integrating NVIDIA cuVS into libraries, databases, and production systems, as well as users running NVIDIA cuVS directly in standalone workflows. These pages cover compatibility, integration patterns, runtime compilation, and extension points that are useful once you move beyond the basic API guides.

## Topic Guides

- [ABI Stability](/developer-guide/abi-stability): understand ABI expectations for developer-facing APIs and downstream integrations.
- [JIT Compilation](/developer-guide/advanced-topics/jit-compilation): understand when NVIDIA cuVS triggers just-in-time compilation, how caches behave, and how to warm up JIT-compiled kernels.
- [Link-time Optimization](/developer-guide/link-time-optimization): use JIT LTO for CUDA compilation, fragment generation, and runtime linking workflows.
- [Compatibility](/user-guide/field-guide/compatibility): understand NVIDIA cuVS release compatibility, ABI windows, and stable binary boundaries.
- [Integration Patterns](/user-guide/field-guide/integration-patterns): compare direct, offloaded, and service-oriented ways to integrate NVIDIA cuVS into products.
- [JIT Compilation](/user-guide/field-guide/jit-compilation): understand when NVIDIA cuVS triggers just-in-time compilation, how caches behave, and how to warm up JIT-compiled kernels.
- [UDF Usage](/user-guide/field-guide/udf-usage): supply custom CUDA distance metrics for IVF-flat search.
Comment thread
cjnolet marked this conversation as resolved.
Outdated
2 changes: 1 addition & 1 deletion fern/pages/api_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ slug: user-guide/api-guides

Use these pages to find task-focused NVIDIA cuVS API examples for clustering, vector indexing, preprocessing, and supporting routines.

NVIDIA cuVS is written in C++ at its core and wrapped by a stable C API layer. The Python, Java, Rust, and Go bindings use that C layer so they can share the same ABI boundary; see [Compatibility](/user-guide/compatibility) for why that matters. These API guides are intended for general use and include examples for supported programming languages where possible, but some guides document C++ concepts explicitly because all NVIDIA cuVS algorithm implementations are C++ at the core.
NVIDIA cuVS is written in C++ at its core and wrapped by a stable C API layer. The Python, Java, Rust, and Go bindings use that C layer so they can share the same ABI boundary; see [Compatibility](/user-guide/field-guide/compatibility) for why that matters. These API guides are intended for general use and include examples for supported programming languages where possible, but some guides document C++ concepts explicitly because all NVIDIA cuVS algorithm implementations are C++ at the core.

## Common Types

Expand Down
4 changes: 2 additions & 2 deletions fern/pages/c_guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Prefer explicit create and destroy functions for every opaque object that owns m

### API Stability

The C API is the stable boundary used by downstream integrations and NVIDIA cuVS language bindings. Add new functions or fields before removing old ones, avoid changing the meaning of existing parameters, and keep [ABI compatibility](/developer-guide/abi-stability) in mind when changing public structs or exported symbols.
The C API is the stable boundary used by downstream integrations and NVIDIA cuVS language bindings. Add new functions or fields before removing old ones, avoid changing the meaning of existing parameters, and keep [ABI compatibility](/developer-guide/advanced-topics/abi-stability) in mind when changing public structs or exported symbols.

### Stateless C APIs

Expand Down Expand Up @@ -131,7 +131,7 @@ Single-GPU C APIs should not require communication libraries or multi-GPU setup.

C APIs may call implementations that use JIT link-time optimization, but the C wrapper should not duplicate JIT LTO policy or expose C++ implementation details. Keep runtime behavior documented at the API level when JIT compilation can affect first-call latency or cache behavior.

For runtime and cache behavior, see [JIT Compilation](/developer-guide/advanced-topics/jit-compilation). For implementation guidance, see [Link-time Optimization](/developer-guide/link-time-optimization).
For runtime and cache behavior, see [JIT Compilation](/user-guide/field-guide/jit-compilation). For implementation guidance, see [Link-time Optimization](/developer-guide/advanced-topics/link-time-optimization).

## Coding Style

Expand Down
2 changes: 1 addition & 1 deletion fern/pages/cpp_guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -256,7 +256,7 @@ void foo(raft::resources const& res)

NVIDIA cuVS is moving new kernels toward JIT link-time optimization. Instead of compiling every kernel variant into the binary, JIT LTO compiles fragments and links the needed combination at runtime.

This helps reduce binary size and enables user-defined functions in NVIDIA cuVS CUDA kernels. For runtime and cache behavior, see [JIT Compilation](/developer-guide/advanced-topics/jit-compilation). For implementation guidance, see [Link-time Optimization](/developer-guide/link-time-optimization).
This helps reduce binary size and enables user-defined functions in NVIDIA cuVS CUDA kernels. For runtime and cache behavior, see [JIT Compilation](/user-guide/field-guide/jit-compilation). For implementation guidance, see [Link-time Optimization](/developer-guide/advanced-topics/link-time-optimization).

## Coding Style

Expand Down
8 changes: 3 additions & 5 deletions fern/pages/developer_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,10 @@ Use these pages when contributing to NVIDIA cuVS or working on integrations that
- [Java Guidelines](/developer-guide/coding-guidelines/java-guidelines): follow NVIDIA cuVS Java API design, native binding, packaging, and resource-management conventions.
- [Python Guidelines](/developer-guide/coding-guidelines/python-guidelines): follow NVIDIA cuVS Python API, packaging, and binding conventions.

## ABI Stability
## Advanced Topics

- [Advanced Topics](/user-guide/advanced-topics): find specialized development topics and low-level implementation guidance.
- [ABI Stability](/developer-guide/abi-stability): understand ABI expectations for developer-facing APIs and downstream integrations.
- [JIT Compilation](/developer-guide/advanced-topics/jit-compilation): understand when NVIDIA cuVS triggers just-in-time compilation and how runtime caches behave.
- [Link-time Optimization](/developer-guide/link-time-optimization): use JIT LTO for CUDA compilation and linking workflows.
- [ABI Stability](/developer-guide/advanced-topics/abi-stability): understand ABI expectations for developer-facing APIs and downstream integrations.
- [Link-time Optimization](/developer-guide/advanced-topics/link-time-optimization): use JIT LTO for CUDA compilation and linking workflows.

## Contributing

Expand Down
2 changes: 1 addition & 1 deletion fern/pages/java_guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Keep generated Panama bindings and native `MemorySegment` details out of the pub

Java APIs are consumed by downstream applications and should change carefully. Add new methods or overloads before removing old ones, preserve existing builder behavior where possible, and avoid changing defaults in ways that silently alter search quality, memory use, or native resource ownership.

The Java bindings should call the NVIDIA cuVS C APIs rather than C++ or CUDA implementation details directly. The C layer is the ABI-stable boundary for bindings, so changes that require new native behavior should usually start with the C API. See [ABI Stability](/developer-guide/abi-stability) for more detail.
The Java bindings should call the NVIDIA cuVS C APIs rather than C++ or CUDA implementation details directly. The C layer is the ABI-stable boundary for bindings, so changes that require new native behavior should usually start with the C API. See [ABI Stability](/developer-guide/advanced-topics/abi-stability) for more detail.

### Resource Lifecycle

Expand Down
25 changes: 18 additions & 7 deletions fern/pages/jit_compilation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
slug: developer-guide/advanced-topics/jit-compilation
slug: user-guide/field-guide/jit-compilation
---

# JIT Compilation
Expand All @@ -8,15 +8,26 @@ NVIDIA cuVS uses Just-in-Time (JIT) [Link-Time Optimization (LTO)](https://devel

The cache validity is:

1. In-memory cache is valid for the lifetime of the process.
2. On-disk cache is valid until a CUDA driver upgrade is performed. The cache can be shared between machines through network or cloud storage, and we recommend storing it in a persistent location. For more details on configuring the on-disk cache, see the CUDA documentation on [JIT Compilation](https://docs.nvidia.com/cuda/cuda-programming-guide/05-appendices/environment-variables.html#jit-compilation). The most relevant environment variables are `CUDA_CACHE_PATH` and `CUDA_CACHE_MAX_SIZE`.
1. In-memory cache: lifetime of the process.
2. On-disk cache: until a CUDA driver upgrade is performed. The cache can be shared between machines through network or cloud storage, and we recommend storing it in a persistent location. For more details on configuring the on-disk cache, see the CUDA documentation on [JIT Compilation](https://docs.nvidia.com/cuda/cuda-programming-guide/05-appendices/environment-variables.html#jit-compilation). The most relevant environment variables are `CUDA_CACHE_PATH` and `CUDA_CACHE_MAX_SIZE`.

JIT compilation is a one-time cost for a given kernel configuration. After the first compilation, you should not expect a steady-state performance loss. For latency-sensitive workflows, run a warmup step before the actual workload so the relevant kernels are compiled and cached ahead of time.

The following NVIDIA cuVS capabilities currently trigger JIT compilation:
The following public NVIDIA cuVS C++ APIs currently trigger JIT compilation. The search entries include single-GPU overloads and multi-GPU overloads where those overloads are exposed.

- IVF-Flat search APIs: [cuvs::neighbors::ivf_flat::search()](/api-reference/cpp-api-neighbors-ivf-flat)
- [cuvs::neighbors::cagra::search()](/api-reference/cpp-api-neighbors-cagra)
- [cuvs::neighbors::ivf_flat::search()](/api-reference/cpp-api-neighbors-ivf-flat)
- [cuvs::neighbors::ivf_pq::search()](/api-reference/cpp-api-neighbors-ivf-pq)
- [cuvs::neighbors::ivf_sq::search()](/api-reference/cpp-api-neighbors-ivf-sq)

Custom distance metrics (UDFs) for IVF-flat search also use JIT compilation. See [UDF Usage](udf_usage.md).
The following C++ APIs can also trigger JIT compilation when they call one of the search paths above internally:

For implementation details on building JIT LTO kernel fragments and linking them at runtime, see [Link-time Optimization](jit_lto_guide.md).
- [cuvs::neighbors::cagra::build()](/api-reference/cpp-api-neighbors-cagra) when graph construction uses `graph_build_params::ivf_pq_params` or `graph_build_params::iterative_search_params`
- [cuvs::neighbors::cagra::extend()](/api-reference/cpp-api-neighbors-cagra) when adding nodes, because the extension path searches the existing CAGRA graph

@divyegala divyegala Jun 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the when necessary here? We should only add if needed

- [cuvs::neighbors::composite::composite_index::search()](/api-reference/cpp-api-neighbors-composite-index) when the composite index searches its CAGRA child indexes
- [cuvs::neighbors::tiered_index::search()](/api-reference/cpp-api-neighbors-tiered-index) when the tiered index is backed by CAGRA, IVF-Flat, or IVF-PQ
- [cuvs::neighbors::all_neighbors::build()](/api-reference/cpp-api-neighbors-all-neighbors) when `graph_build_params` uses IVF-PQ

Custom distance metrics (UDFs) for IVF-flat search also use JIT compilation. See [UDF Usage](/user-guide/field-guide/udf-usage).

For implementation details on building JIT LTO kernel fragments and linking them at runtime, see [Link-time Optimization](/developer-guide/advanced-topics/link-time-optimization).
2 changes: 1 addition & 1 deletion fern/pages/python_guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ If source builds are not being used, install the local RAFT Python artifacts int

### Bindings

Python APIs, like all other NVIDIA cuVS language bindings, should wrap the C APIs and should not call C++ or CUDA implementation code directly. The C layer is the ABI-stable boundary for bindings, so ABI compatibility needs to be maintained there. See [ABI Stability](/developer-guide/abi-stability) for more detail.
Python APIs, like all other NVIDIA cuVS language bindings, should wrap the C APIs and should not call C++ or CUDA implementation code directly. The C layer is the ABI-stable boundary for bindings, so ABI compatibility needs to be maintained there. See [ABI Stability](/developer-guide/advanced-topics/abi-stability) for more detail.

Keep Cython bindings focused on translating Python inputs into NVIDIA cuVS calls and returning Python-friendly outputs. Heavy algorithmic work should stay in C++ or CUDA implementation code.

Expand Down
4 changes: 2 additions & 2 deletions fern/pages/udf_usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

## What this feature does

You can supply **your own CUDA device code** that defines how distance accumulates between a query vector and database vectors **inside the IVF-flat interleaved scan** (the fine search over lists). Technical background on compilation and linking is in [Link-time Optimization](jit_lto_guide.md).
You can supply **your own CUDA device code** that defines how distance accumulates between a query vector and database vectors **inside the IVF-flat interleaved scan** (the fine search over lists). Technical background on compilation and linking is in [Link-time Optimization](/developer-guide/advanced-topics/link-time-optimization).

## Available via C++ APIs

Expand Down Expand Up @@ -63,4 +63,4 @@ More examples: `cpp/tests/neighbors/ann_ivf_flat/test_udf.cu`.
## Further reading

- C++ API reference: [neighbors::ivf_flat](/api-reference/cpp-api-neighbors-ivf-flat)
- JIT LTO architecture and IVF-flat fragments: [Link-time Optimization](jit_lto_guide.md)
- JIT LTO architecture and IVF-flat fragments: [Link-time Optimization](/developer-guide/advanced-topics/link-time-optimization)
9 changes: 3 additions & 6 deletions fern/pages/user_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,14 +60,11 @@ Use these guides when you are ready to apply NVIDIA cuVS APIs, benchmark algorit
- [cuVS Bench Datasets](/user-guide/benchmarking-guide/cu-vs-bench-tool/datasets): prepare datasets, ground truth, binary files, and dataset descriptors.
- [cuVS Bench Backends](/user-guide/benchmarking-guide/cu-vs-bench-tool/backends): understand and extend backend integrations for benchmark execution.

## Compatibility and Integration
## Field Guide

- [Field Guide](advanced_topics.md): find compatibility, runtime compilation, and specialized extension topics.
- [Integration Patterns](/user-guide/field-guide/integration-patterns): compare direct, offloaded, and service-oriented ways to integrate cuVS into products.
- [Compatibility](user_guide/abi_stability.md): understand cuVS release compatibility, ABI windows, and stable binary boundaries.
- [Integration Patterns](user_guide/integration_patterns.md): compare direct, offloaded, and service-oriented ways to integrate cuVS into products.

## Advanced Topics

- [Advanced Topics](advanced_topics.md): find specialized usage topics and low-level implementation guidance.
- [JIT Compilation](jit_compilation.md): understand when cuVS triggers just-in-time compilation and how runtime caches behave.
- [UDF Usage](udf_usage.md): supply custom CUDA distance metrics for IVF-flat search (C++ only, experimental).

Expand Down
6 changes: 5 additions & 1 deletion fern/pages/user_guide/integration_patterns.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
slug: user-guide/field-guide/integration-patterns
---

# Integration Patterns

NVIDIA cuVS is used in several different ways across vector databases, search engines, data platforms, and application libraries. Some products call NVIDIA cuVS directly inside the same process. Others offload expensive index builds to a separate service, container, or serverless worker, then load the resulting index back into the serving system.
Expand Down Expand Up @@ -32,7 +36,7 @@ Products that integrate at the binary level should prefer the NVIDIA cuVS C APIs

ABI stability is especially useful for databases, search engines, language bindings, and packaged applications. It allows vendors to build against one compatible NVIDIA cuVS release while giving users or package managers flexibility to install a newer runtime from the same ABI compatibility window.

For compatibility rules, release windows, and shared library naming, see [Compatibility](/user-guide/compatibility).
For compatibility rules, release windows, and shared library naming, see [Compatibility](/user-guide/field-guide/compatibility).

## Choosing a pattern

Expand Down
Loading
Loading