Skip to content

[DOC]: Fix cuda.bindings documentation build warnings #3383

Open

Description

@mdboom

Problem

The cuda-bindings docs build succeeds but is not warning-free. The 13.5.0 release dry run reported 102 Sphinx warnings. Most are inherited from earlier releases, and not all 102 are necessarily distinct bugs.

Examples (not a complete list)

  • Failed autosummary imports: .rst catalog entries that name objects which cannot be imported (for example cu_memcpy in driver_v2.rst and several stale names in nvml.rst). Sphinx drops the entry and its detail page without leaving a visibly broken row.
  • Malformed reST and duplicate object descriptions reported in the Sphinx output.
  • Missing fragment targets on the legacy pages: 44 in total (34 driver, 10 runtime). They are broken back-references from problematic markup, including unescaped pointer asterisks. The same fragments are missing in the published 13.4.4 pages.

Plan of action

  1. Baseline: save the complete Sphinx warning list from a clean docs build and group it by category (import failure, reST syntax, duplicate description, other).
  2. Autosummary imports: fix or remove each entry that fails to import.
  3. Markup: escape the pointer asterisks that produce the missing fragment targets, then fix the malformed reST.
  4. Duplicates: resolve duplicate object descriptions, either by removing the redundant directive or by adding :no-index: where both are intentional.
  5. Re-verify: rebuild, compare against the baseline, and record the remaining count and any warnings deliberately left.
  6. Prevent regressions: once the count is near zero, make the docs build fail on new warnings (for example -W, or a recorded warning budget).

Activity

  1. added
    documentationImprovements or additions to documentation
    cuda.bindingsEverything related to the cuda.bindings module
    on Nov 5, 2026
  2. self-assigned this
    on Nov 5, 2026
  3. mdboom commented on Nov 5, 2026

    @mdboom
    ContributorAuthor

    Most of this requires changes to the code generator to address, which will be complex to resolve.

    In the meantime, #3387 handles the single non-generated fix we can apply to reduce the number of warnings.

  4. added this to the cuda.bindings next milestone on Nov 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

P2Low priority - Nice to havecuda.bindingsEverything related to the cuda.bindings moduledocumentationImprovements or additions to documentation

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions