summaryrefslogtreecommitdiff
path: root/Documentation/conf.py
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab+huawei@kernel.org>2020-03-20 16:11:03 +0100
committerJonathan Corbet <corbet@lwn.net>2020-03-20 17:01:34 -0600
commit4658b0eb9430e2c228a0a9cc6e66f0b90d3853e1 (patch)
tree8385fa327e4ea5b41663e091eae1a964be9dd9f6 /Documentation/conf.py
parentc44166fe5f38f0559eff1138cca094f3460e2345 (diff)
docs: conf.py: avoid thousands of duplicate label warning on Sphinx
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 a chapter level within any doc, with: autosectionlabel_maxdepth = 2 Fixes: 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst") Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/74f4d8d91c648d7101c45b4b99cc93532f4dadc6.1584716446.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/conf.py')
-rw-r--r--Documentation/conf.py4
1 files changed, 4 insertions, 0 deletions
diff --git a/Documentation/conf.py b/Documentation/conf.py
index fa2bfcd6df1d..9ae8e9abf846 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 = 2
+
# 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")