Skip to contentSkip to conversation

workaround for Sphinx false positive preventing indexing

PATCH Superseded Kevin Paul Reddy Janagari 3 participants 3 messages Jun 27, 2025 – Jun 28, 2025

Subsystems (3)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 workaround for Sphinx false positive preventing indexing

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

---
 Documentation/gpu/drm-kms.rst  | 4 ++++
 Documentation/gpu/drm-uapi.rst | 2 ++
 2 files changed, 6 insertions(+)
Documentation/gpu/drm-kms.rst +4 -0
index abfe220764e1..b18a99869b6d 100644
@@ -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
 ==============
Documentation/gpu/drm-uapi.rst +2 -0
index 69f72e71a96e..e9d7b7282a19 100644
@@ -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:
Signature · 1 line
2.39.5
Tested-by on v2 1/1
#1 lore raw

[also Cc'ing Mauro]

Quoted 45 lines · 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

---
 Documentation/gpu/drm-kms.rst  | 4 ++++
 Documentation/gpu/drm-uapi.rst | 2 ++
 2 files changed, 6 insertions(+)
Documentation/gpu/drm-kms.rst +4 -0
index abfe220764e1..b18a99869b6d 100644
@@ -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
 ==============
Documentation/gpu/drm-uapi.rst +0 -0
index 69f72e71a96e..e9d7b7282a19 100644

Documentation/gpu/drm-uapi.rst DRM specific patterns. Note that ENOTTY has the slightly unintuitive meaning of · line 563

Quoted 10 lines
Documentation/gpu/drm-uapi.rst +2 -0
@@ -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!

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#2 lore raw

Em Sat, 28 Jun 2025 08:30:21 +0700
Bagas Sanjaya <[email protected]> escreveu:

Quoted 10 lines

[also Cc'ing Mauro]

Quoted 7 lines · 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

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
Quoted 46 lines
Quoted 46 lines
---
 Documentation/gpu/drm-kms.rst  | 4 ++++
 Documentation/gpu/drm-uapi.rst | 2 ++
 2 files changed, 6 insertions(+)
Documentation/gpu/drm-kms.rst +4 -0
index abfe220764e1..b18a99869b6d 100644
@@ -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
 ==============
Documentation/gpu/drm-uapi.rst +2 -0
index 69f72e71a96e..e9d7b7282a19 100644
@@ -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::
 
Quoted 7 lines

Documentation/gpu/drm-uapi.rst DRM specific patterns. Note that ENOTTY has the slightly unintuitive meaning of · line 563

Quoted 2 lines
Documentation/gpu/drm-uapi.rst +0 -0
 .. kernel-doc:: drivers/gpu/drm/drm_ioc32.c
    :export:  

Works as expected, thanks!

Thanks,
Mauro