From 58ad30cf91f073a9fab4f8e238b025431343dbf3 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 19 Mar 2020 12:52:01 -0600 Subject: docs: fix reference to core-api/namespaces.rst Fix a couple of dangling links to core-api/namespaces.rst by turning them into proper references. Enable the autosection extension (available since Sphinx 1.4) to make this work. Co-developed-by: Federico Vaga Fixes: fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/") Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/conf.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index 3c7bdf4cd31f..fa2bfcd6df1d 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -38,7 +38,7 @@ needs_sphinx = '1.3' # ones. extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig', 'automarkup', - 'maintainers_include'] + 'maintainers_include', 'sphinx.ext.autosectionlabel' ] # The name of the math extension changed on Sphinx 1.4 if (major == 1 and minor > 3) or (major > 1): -- cgit v1.2.3 From 4658b0eb9430e2c228a0a9cc6e66f0b90d3853e1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 20 Mar 2020 16:11:03 +0100 Subject: 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 Link: https://lore.kernel.org/r/74f4d8d91c648d7101c45b4b99cc93532f4dadc6.1584716446.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation/conf.py') 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") -- cgit v1.2.3