test(core): add cuda.core.__all__ vs public docs consistency check#2347
Open
aryanputta wants to merge 1 commit into
Open
test(core): add cuda.core.__all__ vs public docs consistency check#2347aryanputta wants to merge 1 commit into
aryanputta wants to merge 1 commit into
Conversation
Closes NVIDIA#2326. Parses docs/source/api.rst (autosummary entries and data directives while cuda.core is the active module) and compares the flat public names against cuda.core.__all__ in both directions. Dotted entries such as graph.Graph or checkpoint.Process are submodule namespaces and are excluded. Symbols documented in api_private.rst are accepted as documented so returned-helper docs do not fail the check. The tests skip when cuda.core.__all__ is not defined, so this lands independently of NVIDIA#2300 and activates once NVIDIA#2300 merges. Also adds the __all__-names-resolve guard suggested in the NVIDIA#2300 review. Signed-off-by: Aryan <aryansputta@gmail.com>
Contributor
github-actions
Bot
added
the
cuda.core
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Closes #2326.
Adds
cuda_core/tests/test_api_docs_consistency.py, the follow-on consistency check requested in the #2300 review.What it checks
test_all_exports_resolve: every name incuda.core.__all__resolves viahasattr(the stale-name guard suggested in the review).test_public_symbols_are_documented: fails with "public bycuda.core.__all__but missing from public docs (api.rst)" plus the offending names.test_documented_symbols_are_exported: fails with "documented as public in api.rst but not exported bycuda.core.__all__" plus the offending names.How the docs are parsed
.. module::and.. currentmodule::directives are tracked, so onlyautosummaryentries and.. data::directives active undercuda.corecount. Entries undercuda.core.utilsorcuda.core.textureare excluded automatically.graph.Graphorcheckpoint.Processare submodule namespaces, not flatcuda.corenames, and are excluded.api_private.rstare accepted as documented by their trailing name, so returned helpers such as_device_resources.DeviceResourcesdo not fail the public-docs direction.Ordering with #2300
The tests skip when
cuda.core.__all__is not defined, so this is safe to land before #2300 and activates once #2300 merges. The docs fixture also skips when docs sources are unavailable (installed-wheel test runs).Validation
I do not have a CUDA-capable machine available, so I validated with a stubbed
cuda.coremodule against the real RST files in this repo:__all__set to the list from Add griffe API checking to cuda_core #2300: all 3 tests pass (the currentapi.rst/api_private.rstand the Add griffe API checking to cuda_core #2300__all__are exactly consistent).__all__(current main): all 3 tests skip.__all__and adding a bogus name each fail the corresponding direction with the intended message.ruff checkandruff formatpass.