| Message ID | cover.1584716446.git.mchehab+huawei@kernel.org (mailing list archive) |
|---|---|
| Headers | show |
| Series | Don't generate thousands of new warnings when building docs | expand |
On Fri, 20 Mar 2020 16:11:01 +0100 Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote: > This small series address a regression caused by a new patch at > docs-next (and at linux-next). I don't know how I missed that mess, sorry. I plead distracting times or something like that. Heck, I think I'll blame everything on the plague for at least the next few weeks. Anyway, I've applied this, thanks for cleaning it up. jon
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes: > This small series address a regression caused by a new patch at > docs-next (and at linux-next). > > Before this patch, when a cross-reference to a chapter within the > documentation is needed, we had to add a markup like: > > .. _foo: > > foo > === > > This behavor is now different after this patch: > > 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst") > > As a Sphinx extension now creates automatically a reference > like the above, without requiring any extra markup. > > That, however, comes with a price: it is not possible anymore to have > two sections with the same name within the entire Kernel docs! > > This causes thousands of warnings, as we have sections named > "introduction" on lots of places. > > This series solve this regression by doing two changes: > > 1) The references are now prefixed by the document name. So, > a file named "bar" would have the "foo" reference as "bar:foo". > > 2) It will only use the first two levels. The first one is (usually) the > name of the document, and the second one the chapter name. > > This solves almost all problems we have. Still, there are a few places > where we have two chapters at the same document with the > same name. The first patch addresses this problem. I'm still seeing a lot of warnings. Am I doing something wrong? cheers /linux/Documentation/powerpc/cxl.rst:406: WARNING: duplicate label powerpc/cxl:open, other instance in /linux/Documentation/powerpc/cxl.rst /linux/Documentation/powerpc/cxl.rst:412: WARNING: duplicate label powerpc/cxl:ioctl, other instance in /linux/Documentation/powerpc/cxl.rst /linux/Documentation/powerpc/syscall64-abi.rst:86: WARNING: duplicate label powerpc/syscall64-abi:parameters and return value, other instance in /linux/Documentation/powerpc/syscall64-abi.rst /linux/Documentation/powerpc/syscall64-abi.rst:90: WARNING: duplicate label powerpc/syscall64-abi:stack, other instance in /linux/Documentation/powerpc/syscall64-abi.rst /linux/Documentation/powerpc/syscall64-abi.rst:94: WARNING: duplicate label powerpc/syscall64-abi:register preservation rules, other instance in /linux/Documentation/powerpc/syscall64-abi.rst /linux/Documentation/powerpc/syscall64-abi.rst:103: WARNING: duplicate label powerpc/syscall64-abi:invocation, other instance in /linux/Documentation/powerpc/syscall64-abi.rst /linux/Documentation/powerpc/syscall64-abi.rst:108: WARNING: duplicate label powerpc/syscall64-abi:transactional memory, other instance in /linux/Documentation/powerpc/syscall64-abi.rst /linux/Documentation/powerpc/ultravisor.rst:339: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:351: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:365: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:387: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:406: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:416: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:429: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:438: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:452: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:462: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:477: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:484: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:514: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:521: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:527: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:545: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:561: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:573: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:588: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:594: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:613: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:622: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:633: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:639: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:650: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:658: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:669: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:674: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:688: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:697: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:708: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:721: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:737: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:746: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:757: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:771: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:782: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:789: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:798: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:808: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:819: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:828: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:842: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:849: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:886: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:893: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:900: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:909: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:921: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:928: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:938: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:944: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:957: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:964: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:980: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:1002: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:1017: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:1027: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:1037: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:1053: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:1076: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:1086: WARNING: duplicate label powerpc/ultravisor:return values, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:1096: WARNING: duplicate label powerpc/ultravisor:description, other instance in /linux/Documentation/powerpc/ultravisor.rst /linux/Documentation/powerpc/ultravisor.rst:1105: WARNING: duplicate label powerpc/ultravisor:use cases, other instance in /linux/Documentation/powerpc/ultravisor.rst
Em Tue, 07 Apr 2020 13:46:23 +1000 Michael Ellerman <mpe@ellerman.id.au> escreveu: > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes: > > This small series address a regression caused by a new patch at > > docs-next (and at linux-next). > > ... > > This solves almost all problems we have. Still, there are a few places > > where we have two chapters at the same document with the > > same name. The first patch addresses this problem. > > I'm still seeing a lot of warnings. Am I doing something wrong? > > cheers > > /linux/Documentation/powerpc/cxl.rst:406: WARNING: duplicate label powerpc/cxl:open, other instance in /linux/Documentation/powerpc/cxl.rst ... > /linux/Documentation/powerpc/syscall64-abi.rst:86: WARNING: duplicate label powerpc/syscall64-abi:parameters and return value, other instance in /linux/Documentation/powerpc/syscall64-abi.rst ... > /linux/Documentation/powerpc/ultravisor.rst:339: WARNING: duplicate label powerpc/ultravisor:syntax, other instance in /linux/Documentation/powerpc/ultravisor.rst ... I can't reproduce your issue here at linux-next (+ my pending doc patches). So, I can only provide you some hints. If you see the logs you posted, all of them are related to duplicated labels inside the same file. - The new Sphinx module we're using (sphinx.ext.autosectionlabel) generates references for two levels, within the same document file (after this patch). Looking at the first document (at linux-next version), it has: 1) A first level document title: Coherent Accelerator Interface (CXL) 2) Several second level titles: Introduction Hardware overview AFU Modes MMIO space Interrupts Work Element Descriptor (WED) User API Sysfs Class Udev rules Right now, there's no duplication, but if someone adds, for example, another first-level or second-level title called "Interrupts", then the file will produce a duplicated label and Sphinx will warn. The same would happen if someone adds another title (either first level or second level) called "Coherent Accelerator Interface (CXL)", as this will conflict with the document title. - Now, if the title "Coherent Accelerator Interface (CXL)" got removed, then "Introduction".."Udev rules" will become first level titles. Then, the sections at the "User API": "open", "ioctl"... will become second level titles and it will produce lots of warnings. - That's said, IMHO, this document needs section titles for the two sections under "User API". Adding it would allow removing the document title. See enclosed. Thanks, Mauro powerpc: docs: cxl.rst: mark two section titles as such The User API chapter contains two sub-chapters. Mark them as such. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> diff --git a/Documentation/powerpc/cxl.rst b/Documentation/powerpc/cxl.rst index 920546d81326..d2d77057610e 100644 --- a/Documentation/powerpc/cxl.rst +++ b/Documentation/powerpc/cxl.rst @@ -133,6 +133,7 @@ User API ======== 1. AFU character devices +^^^^^^^^^^^^^^^^^^^^^^^^ For AFUs operating in AFU directed mode, two character device files will be created. /dev/cxl/afu0.0m will correspond to a @@ -395,6 +396,7 @@ read 2. Card character device (powerVM guest only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In a powerVM guest, an extra character device is created for the card. The device is only used to write (flash) a new image on the
On Fri, 20 Mar 2020, Jonathan Corbet <corbet@lwn.net> wrote: > On Fri, 20 Mar 2020 16:11:01 +0100 > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote: > >> This small series address a regression caused by a new patch at >> docs-next (and at linux-next). > > I don't know how I missed that mess, sorry. I plead distracting times or > something like that. Heck, I think I'll blame everything on the plague > for at least the next few weeks. > > Anyway, I've applied this, thanks for cleaning it up. There's still more fallout from the autosectionlabel extension introduced in 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst"), e.g. in i915.rst. The biggest trouble is, if you have headings in kernel-doc comments, Sphinx is unable pinpoint where the dupes are. For example: Documentation/gpu/i915.rst:610: WARNING: duplicate label gpu/i915:layout, other instance in Documentation/gpu/i915.rst However there is no "layout" label in i915.rst. The one being warned about I can dig into based on the line number, but not the second one. You have to resort to grepping the source. And avoiding duplicate subsection headings in completely isolated places is a minefield. BR, Jani.
This small series address a regression caused by a new patch at docs-next (and at linux-next). Before this patch, when a cross-reference to a chapter within the documentation is needed, we had to add a markup like: .. _foo: foo === This behavor is now different after this patch: 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst") As a Sphinx extension now creates automatically a reference like the above, without requiring any extra markup. That, however, comes with a price: it is not possible anymore to have two sections with the same name within the entire Kernel docs! This causes thousands of warnings, as we have sections named "introduction" on lots of places. This series solve this regression by doing two changes: 1) The references are now prefixed by the document name. So, a file named "bar" would have the "foo" reference as "bar:foo". 2) It will only use the first two levels. The first one is (usually) the name of the document, and the second one the chapter name. This solves almost all problems we have. Still, there are a few places where we have two chapters at the same document with the same name. The first patch addresses this problem. The second patch limits the escope of the autosectionlabel. Mauro Carvalho Chehab (2): docs: prevent warnings due to autosectionlabel docs: conf.py: avoid thousands of duplicate label warning on Sphinx Documentation/conf.py | 4 ++++ Documentation/driver-api/80211/mac80211-advanced.rst | 8 ++++---- Documentation/driver-api/dmaengine/index.rst | 4 ++-- Documentation/filesystems/ecryptfs.rst | 11 +++++------ Documentation/kernel-hacking/hacking.rst | 4 ++-- Documentation/media/kapi/v4l2-controls.rst | 8 ++++---- Documentation/networking/snmp_counter.rst | 4 ++-- Documentation/powerpc/ultravisor.rst | 4 ++-- Documentation/security/siphash.rst | 8 ++++---- Documentation/target/tcmu-design.rst | 6 +++--- .../translations/zh_CN/process/5.Posting.rst | 2 +- Documentation/x86/intel-iommu.rst | 3 ++- 12 files changed, 35 insertions(+), 31 deletions(-)