From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>
Subject: [PATCH v2 2/2] docs: conf.py: avoid thousands of duplicate label warning on Sphinx
Date: Fri, 20 Mar 2020 16:11:03 +0100 [thread overview]
Message-ID: <74f4d8d91c648d7101c45b4b99cc93532f4dadc6.1584716446.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1584716446.git.mchehab+huawei@kernel.org>
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>
---
Documentation/conf.py | 4 ++++
1 file changed, 4 insertions(+)
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")
--
2.24.1
next prev parent reply other threads:[~2020-03-20 15:11 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-03-20 15:11 [PATCH v2 0/2] Don't generate thousands of new warnings when building docs Mauro Carvalho Chehab
2020-03-20 15:11 ` [PATCH v2 1/2] docs: prevent warnings due to autosectionlabel Mauro Carvalho Chehab
2020-03-20 15:11 ` Mauro Carvalho Chehab [this message]
2020-03-20 23:10 ` [PATCH v2 0/2] Don't generate thousands of new warnings when building docs Jonathan Corbet
2020-04-16 10:05 ` Jani Nikula
2020-04-07 3:46 ` Michael Ellerman
2020-04-08 11:40 ` Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=74f4d8d91c648d7101c45b4b99cc93532f4dadc6.1584716446.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel.org \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).