lkml.org 
[lkml]   [2020]   [Mar]   [20]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
From
Subject[PATCH] docs: conf.py: avoid thousands of duplicate label warning on Sphinx
Date
The autosectionlabel extension is nice, as it allows to refer to
a section by its name without requiring any extra tag to create
a reference name.

However, on its default, it has two serious problems:

1) the namespace is global. So, two files with different
"introduction" section would create a label with the
same name. This is easily solvable by forcing the extension
to prepend the file name with:

autosectionlabel_prefix_document = True

2) It doesn't work hierarchically. So, if there are two level 1
sessions (let's say, one labeled "open" and another one "ioctl")
and both have a level 2 "synopsis" label, both section 2 will
have the same identical name.

Currently, there's no way to tell Sphinx to create an
hierarchical reference like:

open / synopsis
ioctl / synopsis

This causes around 800 warnings. So, the fix should be to
not let autosectionlabel to produce references for anything
that it is not at level one, with:

autosectionlabel_maxdepth = 1

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/conf.py | 4 ++++
1 file changed, 4 insertions(+)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index fa2bfcd6df1d..f193bae85a36 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -40,6 +40,10 @@ extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain',
'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
'maintainers_include', 'sphinx.ext.autosectionlabel' ]

+# Ensure that autosectionlabel will produce unique names
+autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = 1
+
# The name of the math extension changed on Sphinx 1.4
if (major == 1 and minor > 3) or (major > 1):
extensions.append("sphinx.ext.imgmath")
--
2.24.1
\
 
 \ /
  Last update: 2020-03-20 12:13    [W:0.111 / U:1.440 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site