Include cuda.bindings.nvml in docs

[mdboom]

I just completely neglected to include cuda.bindings.nvml bindings in the docs. This adds them.

This also updates the release note about cuda.bindings.nvml -- the text there applies to cuda.core.system, not cuda.bindings.nvml.

(Relatedly, cuda.core.system is already integrated in the docs).

New enum documenter

Before this PR, if you automatically document an enum class, you get something that looks like this. In other words, since an enum is a subclass of int, it documents all of the methods that come from int. This is really confusing. Additionally, it doesn't document the meaning of each of the enumeration values (only their name and value). Since the FastEnum work landed, each enumeration value actually has a docstring that we can pull in.

Elsewhere in the code base, this is worked around by explicitly writing out each of the values by hand, with a docstring: https://github.com/NVIDIA/cuda-python/blob/main/cuda_bindings/docs/source/module/driver.rst?plain=1#L120

.. autoclass:: cuda.bindings.driver.CUctx_flags
    .. autoattribute:: cuda.bindings.driver.CUctx_flags.CU_CTX_SCHED_AUTO
        Automatic scheduling
    .. autoattribute:: cuda.bindings.driver.CUctx_flags.CU_CTX_SCHED_SPIN
        Set spin as default scheduling
    .. autoattribute:: cuda.bindings.driver.CUctx_flags.CU_CTX_SCHED_YIELD
        Set yield as default scheduling
    .. autoattribute:: cuda.bindings.driver.CUctx_flags.CU_CTX_SCHED_BLOCKING_SYNC
        Set blocking synchronization as default scheduling
    .. autoattribute:: cuda.bindings.driver.CUctx_flags.CU_CTX_BLOCKING_SYNC
        Set blocking synchronization as default scheduling [Deprecated]
    .. autoattribute:: cuda.bindings.driver.CUctx_flags.CU_CTX_SCHED_MASK
    .. autoattribute:: cuda.bindings.driver.CUctx_flags.CU_CTX_MAP_HOST
        [Deprecated]

This manual approach is not going to scale for NVML, which has 112 enums, some of which have more than 300 values.

So, it was easy enough to write a Sphinx extension to handle this automatically. We were using a third-party extension to automatically document enums (enum_tools.autoenum), but as far as I can tell, that has bit-rotted and hasn't been working for some time. In any event, it can't be used to automatically extract docstrings from enum values (since that feature doesn't exist in the stdlib enum implementation).

This greatly simplifies documenting NVML, and as a follow-up, we can go through and remove all of the places elsewhere in the doc where manually documenting enumeration values is no longer necessary.

[mdboom]

/ok to test

[mdboom]

/ok to test

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[mdboom]

/ok to test

[cpcloud]

Building the bindings docs locally now emits a docutils error for this page: docstring of cuda.bindings.nvml.device_get_virtualization_mode:6: ERROR: Unknown target name: "nvml_gpu_virtualization". The same happens for device_set_virtualization_mode. The underlying autogenerated docstring text includes NVML_GPU_VIRTUALIZATION_?, which docutils is parsing as a broken reference, so these entries currently add broken pages to the new NVML docs.

[cpcloud]

Including GpmMetricId also adds a new NVML-specific docutils warning in the local docs build: docstring of cuda.bindings.nvml.GpmMetricId:1: WARNING: Inline emphasis start-string without end-string. This looks like it comes from one of the enum member docstrings containing 0.0 - 100.0 *..., so it would be good to clean that up before merging the new autosummary page.

[cpcloud]

I built the bindings docs locally in a pixi-backed Sphinx environment and found a couple of NVML-specific docutils issues introduced by the new nvml page.

• device_get_virtualization_mode and device_set_virtualization_mode now surface Unknown target name: "nvml_gpu_virtualization" errors.
• GpmMetricId now surfaces an inline-emphasis warning from one of its member docstrings.

Once those newly exposed doc issues are addressed, the rest of the NVML docs wiring and the enum autosummary flow looked good in my local build.

[mdboom]

I built the bindings docs locally in a pixi-backed Sphinx environment and found a couple of NVML-specific docutils issues introduced by the new nvml page.

• device_get_virtualization_mode and device_set_virtualization_mode now surface Unknown target name: "nvml_gpu_virtualization" errors.
• GpmMetricId now surfaces an inline-emphasis warning from one of its member docstrings.

Once those newly exposed doc issues are addressed, the rest of the NVML docs wiring and the enum autosummary flow looked good in my local build.

Since these docstrings come from the C headers, it's going to be multiple steps to get them right, but right we shall...

[cpcloud]

@mdboom I'm happy to unblock this if you want do that in a follow-up. Fine by me.

[mdboom]

@mdboom I'm happy to unblock this if you want do that in a follow-up. Fine by me.

I decided to just patch them at the end of the file (since it's easy to add content to the end from the generator).

Longer term, these are bugs to fix in the doxygen-to-rst conversion step in the generator, or bugs to file against the C header content.

I actually have it on my TODO to refactor the doc converter in the next few weeks, so it will be easiest to handle that then. In the meantime, this is just a bit of a workaround here that at least won't create dangling references.

[github-actions]

Doc Preview CI
Preview removed because the pull request was closed or merged.