NVIDIA / NVIDIA/cccl

Build versioned docs

Open
#5,773 1 comment 0 reactions 1 assignee Claimed by @jrhemstad View on GitHub
Dominant language
C++
Stars
2.5k
Forks
486
Avg merge
2d 6h
Merged PRs (30d)
295

Description

Versioned docs are important because it keeps a snapshot of what's released/available in a particular version. In particular, we often embed examples in the docstrings (ex: https://github.com/NVIDIA/cccl/pull/5614) and versioned docs is the only way we don't lose them.

This feature is supported out of box by the NVIDIA Sphinx theme. NVIDIA/cuda-python already has it enabled for a long time and can be used as a reference.

One gotcha is that we have two separate versions currently in this repo (NVIDIA/cuda-python has 4...):
- C++ (Thrust, CUB, libcudacxx)
- Python (cuda.cccl)

None of the major Sphinx themes, including ours, supports such a multi-version scheme. The workaround found in cuda-python is that we build the docs separately for each project, and stitch them under the same root path. Cross-referencing across projects needs to be hard-coded, though, like in the old days when this repo still used repodocs. (I dunno if it is still the case today.)

This subject is particularly urgent for the Python side, because we are still evolving very fast and offer no stable interface yet. @nv-kriehl has reported offline, for example, that the code samples in the main branch do not work with released packages.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.