[PATCH v2] workaround for Sphinx false positive preventing indexing

[Mauro Carvalho Chehab]

Em Sat, 28 Jun 2025 08:30:21 +0700
Bagas Sanjaya <bagasdotme at 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 at 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 at gmail.com>
> 



Thanks,
Mauro