Skip to content
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.

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

Suppress doc build warnings #152

Open
leofang opened this issue Oct 10, 2024 · 4 comments
Open

Suppress doc build warnings #152

leofang opened this issue Oct 10, 2024 · 4 comments
Labels
cuda.bindings Everything related to the cuda.bindings module documentation Improvements or additions to documentation P2 Low priority - Nice to have triage Needs the team's attention

Comments

@leofang
Copy link
Member

leofang commented Oct 10, 2024

According to @vzhurba01 the warnings are mostly due to the fact that some types are shared (?) across multiple modules and they are benign. Would be nice to figure out a way to suppress this particular warning, so that other warnings are not cluttered in-between and become noise.

@leofang leofang added documentation Improvements or additions to documentation P2 Low priority - Nice to have labels Oct 10, 2024
@leofang leofang added this to the cuda-python 12-next, 11-next milestone Oct 10, 2024
@leofang leofang added the cuda.bindings Everything related to the cuda.bindings module label Oct 10, 2024
@leofang
Copy link
Member Author

leofang commented Oct 12, 2024

An example warning

/local/home/leof/dev/cuda-python/docs_src/docstring of cuda.bindings.driver.cuMemcpy2D:22: WARNING: more than one target found for cross-reference 'srcPitch': cuda.bindings.driver.CUDA_MEMCPY2D_st.srcPitch, cuda.bindings.driver.CUDA_MEMCPY3D_st.srcPitch, cuda.bindings.driver.CUDA_MEMCPY3D_PEER_st.srcPitch, cuda.bindings.driver.CUDA_MEMCPY2D_v2.srcPitch, cuda.bindings.driver.CUDA_MEMCPY2D.srcPitch, cuda.bindings.driver.CUDA_MEMCPY3D_v2.srcPitch, cuda.bindings.driver.CUDA_MEMCPY3D.srcPitch, cuda.bindings.driver.CUDA_MEMCPY3D_PEER_v1.srcPitch, cuda.bindings.driver.CUDA_MEMCPY3D_PEER.srcPitch [ref.python]

@leofang
Copy link
Member Author

leofang commented Oct 12, 2024

I believe this is a legitimate warning, as the raw docstring is :py:obj:`~.srcPitch`, which does not provide the struct name that the srcPitch member belongs to. However, there's nothing we can do as it's already missing from the original doc source:
https://docs.nvidia.com/cuda/cuda-driver-api/group__CUDA__MEM.html#group__CUDA__MEM_1g27f885b30c34cc20a663a671dbf6fc27
so we do need to find a way to just suppress such warnings...

@leofang
Copy link
Member Author

leofang commented Oct 12, 2024

@vzhurba01 this looks like a docgen bug:
https://github.com/NVIDIA/cuda-python/blob/f9f67c8ba2698c56eede95fe1b55bca3ce26d9a4/cuda_bindings/cuda/bindings/driver.pyx.in#L31341

Sphinx output:

docstring of cuda.bindings.driver.cuStreamSynchronize:12: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
docstring of cuda.bindings.driver.cuStreamSynchronize:17: CRITICAL: Unexpected section title.

Returns
------- [docutils]
docstring of cuda.bindings.driver.cuStreamSynchronize:22: CRITICAL: Unexpected section title.

See Also
-------- [docutils]

@leofang
Copy link
Member Author

leofang commented Oct 12, 2024

This one too:
https://github.com/NVIDIA/cuda-python/blob/f9f67c8ba2698c56eede95fe1b55bca3ce26d9a4/cuda_bindings/cuda/bindings/runtime.pyx.in#L20967

Sphinx output:

docstring of cuda.bindings.runtime.cudaMemcpy:19: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
docstring of cuda.bindings.runtime.cudaMemcpy:30: CRITICAL: Unexpected section title.

Returns
------- [docutils]
docstring of cuda.bindings.runtime.cudaMemcpy:35: CRITICAL: Unexpected section title.

See Also
-------- [docutils]

leofang added a commit to leofang/cuda-python that referenced this issue Oct 12, 2024
@leofang leofang added the triage Needs the team's attention label Jan 18, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cuda.bindings Everything related to the cuda.bindings module documentation Improvements or additions to documentation P2 Low priority - Nice to have triage Needs the team's attention
Projects
None yet
Development

No branches or pull requests

1 participant