cuda-python icon indicating copy to clipboard operation
cuda-python copied to clipboard

Suppress doc build warnings

Open leofang opened this issue 1 year ago • 4 comments

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 avatar Oct 10 '24 17:10 leofang

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 avatar Oct 12 '24 00:10 leofang

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 avatar Oct 12 '24 00:10 leofang

@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 avatar Oct 12 '24 01:10 leofang

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 avatar Oct 12 '24 01:10 leofang