[PATCH v2] workaround for Sphinx false positive preventing indexing

[PATCH v2] workaround for Sphinx false positive preventing indexing

[Kevin Paul Reddy Janagari]

Functions drm_format_info, drm_modeset_lock, drm_ioctl_flags are not being
indexed in the documentation because there are structs with the same name 
and sphinx is only indexing one of them, Added them to namespaces as a
workaround for suppressing the warnings and indexing the functions

This is a bug of Sphinx >=3.1, first reported by Mauro in September 2020
Link: https://github.com/sphinx-doc/sphinx/issues/8241

Signed-off-by: Kevin Paul Reddy Janagari <kevinpaul468@gmail.com>
---
 Documentation/gpu/drm-kms.rst  | 4 ++++
 Documentation/gpu/drm-uapi.rst | 2 ++
 2 files changed, 6 insertions(+)

diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
index abfe220764e1..b18a99869b6d 100644
--- a/Documentation/gpu/drm-kms.rst
+++ b/Documentation/gpu/drm-kms.rst
@@ -357,8 +357,10 @@ Format Functions Reference
 .. kernel-doc:: include/drm/drm_fourcc.h
    :internal:
 
+.. c:namespace-push:: gpu_drm
 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
    :export:
+.. c:namespace-pop::
 
 .. _kms_dumb_buffer_objects:
 
@@ -473,8 +475,10 @@ KMS Locking
 .. kernel-doc:: include/drm/drm_modeset_lock.h
    :internal:
 
+.. c:namespace:: gpu_drm
 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
    :export:
+.. c:namespace-pop::
 
 KMS Properties
 ==============
diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
index 69f72e71a96e..e9d7b7282a19 100644
--- a/Documentation/gpu/drm-uapi.rst
+++ b/Documentation/gpu/drm-uapi.rst
@@ -554,8 +554,10 @@ DRM specific patterns. Note that ENOTTY has the slightly unintuitive meaning of
 .. kernel-doc:: include/drm/drm_ioctl.h
    :internal:
 
+.. c:namespace-push:: gpu_drm
 .. kernel-doc:: drivers/gpu/drm/drm_ioctl.c
    :export:
+.. c:namespace-pop::
 
 .. kernel-doc:: drivers/gpu/drm/drm_ioc32.c
    :export:
-- 
2.39.5

Re: [PATCH v2] workaround for Sphinx false positive preventing indexing

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 2216 bytes --]

[also Cc'ing Mauro]

On Fri, Jun 27, 2025 at 05:27:18PM +0530, Kevin Paul Reddy Janagari wrote:
> Functions drm_format_info, drm_modeset_lock, drm_ioctl_flags are not being
> indexed in the documentation because there are structs with the same name 
> and sphinx is only indexing one of them, Added them to namespaces as a
> workaround for suppressing the warnings and indexing the functions
> 
> This is a bug of Sphinx >=3.1, first reported by Mauro in September 2020
> Link: https://github.com/sphinx-doc/sphinx/issues/8241
> 
> Signed-off-by: Kevin Paul Reddy Janagari <kevinpaul468@gmail.com>
> ---
>  Documentation/gpu/drm-kms.rst  | 4 ++++
>  Documentation/gpu/drm-uapi.rst | 2 ++
>  2 files changed, 6 insertions(+)
> 
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index abfe220764e1..b18a99869b6d 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -357,8 +357,10 @@ Format Functions Reference
>  .. kernel-doc:: include/drm/drm_fourcc.h
>     :internal:
>  
> +.. c:namespace-push:: gpu_drm
>  .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
>     :export:
> +.. c:namespace-pop::
>  
>  .. _kms_dumb_buffer_objects:
>  
> @@ -473,8 +475,10 @@ KMS Locking
>  .. kernel-doc:: include/drm/drm_modeset_lock.h
>     :internal:
>  
> +.. c:namespace:: gpu_drm
>  .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
>     :export:
> +.. c:namespace-pop::
>  
>  KMS Properties
>  ==============
> diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
> index 69f72e71a96e..e9d7b7282a19 100644
> --- a/Documentation/gpu/drm-uapi.rst
> +++ b/Documentation/gpu/drm-uapi.rst
> @@ -554,8 +554,10 @@ DRM specific patterns. Note that ENOTTY has the slightly unintuitive meaning of
>  .. kernel-doc:: include/drm/drm_ioctl.h
>     :internal:
>  
> +.. c:namespace-push:: gpu_drm
>  .. kernel-doc:: drivers/gpu/drm/drm_ioctl.c
>     :export:
> +.. c:namespace-pop::
>  
>  .. kernel-doc:: drivers/gpu/drm/drm_ioc32.c
>     :export:

Works as expected, thanks!

Tested-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2] workaround for Sphinx false positive preventing indexing

[Mauro Carvalho Chehab]

Em Sat, 28 Jun 2025 08:30:21 +0700
Bagas Sanjaya <bagasdotme@gmail.com> escreveu:

> [also Cc'ing Mauro]
> 
> On Fri, Jun 27, 2025 at 05:27:18PM +0530, Kevin Paul Reddy Janagari wrote:
> > Functions drm_format_info, drm_modeset_lock, drm_ioctl_flags are not being
> > indexed in the documentation because there are structs with the same name 
> > and sphinx is only indexing one of them, Added them to namespaces as a
> > workaround for suppressing the warnings and indexing the functions
> > 
> > This is a bug of Sphinx >=3.1, first reported by Mauro in September 2020
> > Link: https://github.com/sphinx-doc/sphinx/issues/8241

Yes, that's the issue. It is probably worth to also a link to the still
open one:

	https://github.com/sphinx-doc/sphinx/pull/8313

> > 
> > Signed-off-by: Kevin Paul Reddy Janagari <kevinpaul468@gmail.com>
> > ---
> >  Documentation/gpu/drm-kms.rst  | 4 ++++
> >  Documentation/gpu/drm-uapi.rst | 2 ++
> >  2 files changed, 6 insertions(+)
> > 
> > diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> > index abfe220764e1..b18a99869b6d 100644
> > --- a/Documentation/gpu/drm-kms.rst
> > +++ b/Documentation/gpu/drm-kms.rst
> > @@ -357,8 +357,10 @@ Format Functions Reference
> >  .. kernel-doc:: include/drm/drm_fourcc.h
> >     :internal:
> >  
> > +.. c:namespace-push:: gpu_drm
> >  .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
> >     :export:
> > +.. c:namespace-pop::
> >  
> >  .. _kms_dumb_buffer_objects:
> >  
> > @@ -473,8 +475,10 @@ KMS Locking
> >  .. kernel-doc:: include/drm/drm_modeset_lock.h
> >     :internal:
> >  
> > +.. c:namespace:: gpu_drm
> >  .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
> >     :export:
> > +.. c:namespace-pop::
> >  
> >  KMS Properties
> >  ==============
> > diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
> > index 69f72e71a96e..e9d7b7282a19 100644
> > --- a/Documentation/gpu/drm-uapi.rst
> > +++ b/Documentation/gpu/drm-uapi.rst
> > @@ -554,8 +554,10 @@ DRM specific patterns. Note that ENOTTY has the slightly unintuitive meaning of
> >  .. kernel-doc:: include/drm/drm_ioctl.h
> >     :internal:
> >  
> > +.. c:namespace-push:: gpu_drm
> >  .. kernel-doc:: drivers/gpu/drm/drm_ioctl.c
> >     :export:
> > +.. c:namespace-pop::
> >  
> >  .. kernel-doc:: drivers/gpu/drm/drm_ioc32.c
> >     :export:  
> 
> Works as expected, thanks!
> 
> Tested-by: Bagas Sanjaya <bagasdotme@gmail.com>
> 



Thanks,
Mauro