Fix new html build warnings from next-20201001
Subsystems (10)
cover Fix new html build warnings from next-20201001
There are some new warnings when building the documentation from yesterday's linux next. This small series fix them.
- patch 1 documents two new kernel-doc parameters on a net core file. I used the commit log in order to help documenting them;
- patch 2 fixes some tags at UMLv2 howto;
- patches 3 and 5 add some new documents at the corresponding index file.
- patch 4 changes kernel-doc script for it to recognize typedef enums.
Patch 4 should probably be merged via docs tree, but the others are against stuff recently added at linux-next. So, the better is to merge them directly at the trees which introduced the issue.
-
As a reference, the patches fixing all html build warnings are at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=sphinx3-fixes-v3
Such series also adds support for Sphinx versions 3.1 and above.
It should be noticed that, with Sphinx version 3 and above, there are a few new warnings, because currently Sphinx assumes a that names are unique for all C symbols. There are a few cases where we have the same name for a function and for a struct at the Kernel. Upstream is already working on a solution for that.
So, for now, I recomend doing html builds with version < 3.
Mauro Carvalho Chehab (6):
net: core: document two new elements of struct net_device
docs: vcpu.rst: fix some build warnings
docs: virt: user_mode_linux_howto_v2.rst: fix a literal block markup
docs: i2c: index.rst: add slave-testunit-backend.rst
scripts: kernel-doc: add support for typedef enum
docs: gpio: add a new document to its index.rst
Documentation/admin-guide/gpio/index.rst | 1 + .../admin-guide/hw-vuln/l1d_flush.rst | 3 +-- Documentation/i2c/index.rst | 1 + Documentation/virt/kvm/devices/vcpu.rst | 26 +++++++++---------- .../virt/uml/user_mode_linux_howto_v2.rst | 1 + include/linux/netdevice.h | 5 ++++ scripts/kernel-doc | 15 ++++++++--- 7 files changed, 33 insertions(+), 19 deletions(-)
Signature · 1 line
2.26.2
PATCH 1/6 net: core: document two new elements of struct net_device
As warned by "make htmldocs", there are two new struct elements that aren't documented:
../include/linux/netdevice.h:2159: warning: Function parameter or member 'unlink_list' not described in 'net_device' ../include/linux/netdevice.h:2159: warning: Function parameter or member 'nested_level' not described in 'net_device'
--- include/linux/netdevice.h | 5 +++++ 1 file changed, 5 insertions(+)
include/linux/netdevice.h +5 -0
@@ -1843,6 +1843,11 @@ enum netdev_priv_flags {* @udp_tunnel_nic: UDP tunnel offload state * @xdp_state: stores info on attached XDP BPF programs * +* @nested_level: Used as as a parameter of spin_lock_nested() of +* dev->addr_list_lock. +* @unlink_list: As netif_addr_lock() can be called recursively, +* keep a list of interfaces to be deleted. +* * FIXME: cleanup struct net_device such that network protocol info * moves out. */
Signature · 1 line
2.26.2
Re: [PATCH 1/6] net: core: document two new elements of struct net_device
From: Mauro Carvalho Chehab <[email protected]>
Date: Fri, 2 Oct 2020 07:49:45 +0200
Quoted 8 lines
As warned by "make htmldocs", there are two new struct elements that aren't documented:
../include/linux/netdevice.h:2159: warning: Function parameter or member 'unlink_list' not described in 'net_device'../include/linux/netdevice.h:2159: warning: Function parameter or member 'nested_level' not described in 'net_device'Fixes 1fc70edb7d7b ("net: core: add nested_level variable in net_device")Signed-off-by Mauro Carvalho Chehab <[email protected]>
Applied, thank you.
PATCH 2/6 docs: vcpu.rst: fix some build warnings
In reply to Mauro Carvalho ChehabAs warned with make htmldocs:
.../Documentation/virt/kvm/devices/vcpu.rst:70: WARNING: Malformed table. Text in column margin in table line 2.
======= ====================================================== -ENODEV: PMUv3 not supported or GIC not initialized -ENXIO: PMUv3 not properly configured or in-kernel irqchip not
configured as required prior to calling this attribute
-EBUSY: PMUv3 already initialized
-EINVAL: Invalid filter range
======= ======================================================
The ':' character for two lines are above the size of the column. Besides that, other tables at the file doesn't use ':', so just drop them.
While here, also fix this warning also introduced at the same patch:
.../Documentation/virt/kvm/devices/vcpu.rst:88: WARNING: Block quote ends without a blank line; unexpected unindent.
By marking the C code as a literal block.
--- Documentation/virt/kvm/devices/vcpu.rst | 26 ++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-)
Documentation/virt/kvm/devices/vcpu.rst +13 -13
@@ -67,25 +67,25 @@ irqchip. :Returns: ======= ====================================================== - -ENODEV: PMUv3 not supported or GIC not initialized - -ENXIO: PMUv3 not properly configured or in-kernel irqchip not + -ENODEV PMUv3 not supported or GIC not initialized + -ENXIO PMUv3 not properly configured or in-kernel irqchip not configured as required prior to calling this attribute - -EBUSY: PMUv3 already initialized - -EINVAL: Invalid filter range + -EBUSY PMUv3 already initialized + -EINVAL Invalid filter range ======= ====================================================== -Request the installation of a PMU event filter described as follows: +Request the installation of a PMU event filter described as follows:: -struct kvm_pmu_event_filter { - __u16 base_event; - __u16 nevents; + struct kvm_pmu_event_filter { + __u16 base_event; + __u16 nevents; -#define KVM_PMU_EVENT_ALLOW 0 -#define KVM_PMU_EVENT_DENY 1 + #define KVM_PMU_EVENT_ALLOW 0 + #define KVM_PMU_EVENT_DENY 1 - __u8 action; - __u8 pad[3]; -}; + __u8 action; + __u8 pad[3]; + }; A filter range is defined as the range [@base_event, @base_event + @nevents), together with an @action (KVM_PMU_EVENT_ALLOW or KVM_PMU_EVENT_DENY). The
Signature · 1 line
2.26.2
Re: [PATCH 2/6] docs: vcpu.rst: fix some build warnings
Quoted 63 lines · Mauro Carvalho Chehab
As warned with make htmldocs:
.../Documentation/virt/kvm/devices/vcpu.rst:70: WARNING: Malformed table. Text in column margin in table line 2.======= ======================================================
-ENODEV: PMUv3 not supported or GIC not initialized-ENXIO: PMUv3 not properly configured or in-kernel irqchip not
configured as required prior to calling this attribute
-EBUSY: PMUv3 already initialized
-EINVAL: Invalid filter range
======= ======================================================The ':' character for two lines are above the size of the column. Besides that, other tables at the file doesn't use ':', so just drop them.
While here, also fix this warning also introduced at the same patch:
.../Documentation/virt/kvm/devices/vcpu.rst:88: WARNING: Block quote ends without a blank line; unexpected unindent.By marking the C code as a literal block.
Fixes 8be86a5eec04 ("KVM: arm64: Document PMU filtering API")Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/virt/kvm/devices/vcpu.rst | 26 ++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-)Documentation/virt/kvm/devices/vcpu.rst +10
-10@@ -67,25 +67,25 @@ irqchip. :Returns: ======= ====================================================== - -ENODEV: PMUv3 not supported or GIC not initialized - -ENXIO: PMUv3 not properly configured or in-kernel irqchip not + -ENODEV PMUv3 not supported or GIC not initialized + -ENXIO PMUv3 not properly configured or in-kernel irqchip not configured as required prior to calling this attribute - -EBUSY: PMUv3 already initialized - -EINVAL: Invalid filter range + -EBUSY PMUv3 already initialized + -EINVAL Invalid filter range ======= ====================================================== -Request the installation of a PMU event filter described as follows: +Request the installation of a PMU event filter described as follows:: -struct kvm_pmu_event_filter { - __u16 base_event; - __u16 nevents; + struct kvm_pmu_event_filter { + __u16 base_event; + __u16 nevents; -#define KVM_PMU_EVENT_ALLOW 0 -#define KVM_PMU_EVENT_DENY 1 + #define KVM_PMU_EVENT_ALLOW 0 + #define KVM_PMU_EVENT_DENY 1
Documentation/virt/kvm/devices/vcpu.rst irqchip. · line 91
Quoted 10 lines
Documentation/virt/kvm/devices/vcpu.rst +3
-3- __u8 action; - __u8 pad[3]; -}; + __u8 action; + __u8 pad[3]; + }; A filter range is defined as the range [@base_event, @base_event + @nevents), together with an @action (KVM_PMU_EVENT_ALLOW or KVM_PMU_EVENT_DENY). The
PATCH 3/6 docs: virt: user_mode_linux_howto_v2.rst: fix a literal block markup
In reply to Mauro Carvalho ChehabThere's a missing new line for a literal block:
.../Documentation/virt/uml/user_mode_linux_howto_v2.rst:682: WARNING: Unexpected indentation.
--- Documentation/virt/uml/user_mode_linux_howto_v2.rst | 1 + 1 file changed, 1 insertion(+)
Documentation/virt/uml/user_mode_linux_howto_v2.rst +1 -0
@@ -679,6 +679,7 @@ Starting UML We can now run UML. :: + # linux mem=2048M umid=TEST \ ubd0=Filesystem.img \ vec0:transport=tap,ifname=tap0,depth=128,gro=1 \
Signature · 7 lines
2.26.2 _______________________________________________ linux-um mailing list [email protected] http://lists.infradead.org/mailman/listinfo/linux-um
Re: [PATCH 3/6] docs: virt: user_mode_linux_howto_v2.rst: fix a literal block markup
Quoted 16 lines · Mauro Carvalho Chehab
There's a missing new line for a literal block:
.../Documentation/virt/uml/user_mode_linux_howto_v2.rst:682: WARNING: Unexpected indentation.Fixes 04301bf5b072 ("docs: replace the old User Mode Linux HowTo with a new one")Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/virt/uml/user_mode_linux_howto_v2.rst | 1 + 1 file changed, 1 insertion(+)Documentation/virt/uml/user_mode_linux_howto_v2.rst +0
-0
Documentation/virt/uml/user_mode_linux_howto_v2.rst Starting UML · line 685
Quoted 7 lines
Documentation/virt/uml/user_mode_linux_howto_v2.rst +1
-0@@ -679,6 +679,7 @@ Starting UML We can now run UML. :: + # linux mem=2048M umid=TEST \ ubd0=Filesystem.img \ vec0:transport=tap,ifname=tap0,depth=128,gro=1 \
Thanks.
Signature · 3 lines
Anton R. Ivanov Cambridgegreys Limited. Registered in England. Company Number 10273661 https://www.cambridgegreys.com/
PATCH 4/6 docs: i2c: index.rst: add slave-testunit-backend.rst
In reply to Mauro Carvalho ChehabAs warned by Sphinx:
.../Documentation/i2c/slave-testunit-backend.rst: WARNING: document isn't included in any toctree
This document is not included anywhere.
--- Documentation/admin-guide/hw-vuln/l1d_flush.rst | 3 +-- Documentation/i2c/index.rst | 1 + 2 files changed, 2 insertions(+), 2 deletions(-)
Documentation/admin-guide/hw-vuln/l1d_flush.rst +1 -2
@@ -22,8 +22,7 @@ mechanism Usage Guidelines ---------------- -Please see document: :ref:`Documentation/userspace-api/spec_ctrl.rst` for -details. +Please see document: :doc:`/userspace-api/spec_ctrl` for details. **NOTE**: The feature is disabled by default, applications need to specifically opt into the feature to enable it.
Documentation/i2c/index.rst +1 -0
@@ -38,6 +38,7 @@ Debugging gpio-fault-injection i2c-stub + slave-testunit-backend Slave I2C =========
Signature · 1 line
2.26.2
Re: [PATCH 4/6] docs: i2c: index.rst: add slave-testunit-backend.rst
Hi Mauro,
Documentation/i2c/index.rst Debugging · line 41
Quoted 8 lines
index
8a2ad3845191..9b8df313902c100644Documentation/i2c/index.rst +1
-0@@ -38,6 +38,7 @@ Debugging gpio-fault-injection i2c-stub + slave-testunit-backend
Yeah, it is missing, but this is the wrong paragraph to add it. For consistency, I'd like to create a seperate patch to fix it and merge it via I2C. Do you mind dropping this hunk? I'd credit you with Reported-by, of course.
Thanks,
Wolfram
Re: [PATCH 4/6] docs: i2c: index.rst: add slave-testunit-backend.rst
Em Fri, 2 Oct 2020 09:54:04 +0200
Wolfram Sang <[email protected]> escreveu:
Quoted 7 lines
Hi Mauro,
Quoted 5 lines
index
8a2ad3845191..9b8df313902c100644Documentation/i2c/index.rst +0
-0@@ -38,6 +38,7 @@ Debugging
Quoted 7 lines
Documentation/i2c/index.rst Debugging · line 41
Quoted 3 lines
Documentation/i2c/index.rst +1
-0gpio-fault-injection i2c-stub + slave-testunit-backendYeah, it is missing, but this is the wrong paragraph to add it. For consistency, I'd like to create a seperate patch to fix it and merge it via I2C. Do you mind dropping this hunk?
Yeah, sure!
Quoted 2 lines
I'd credit you with
Reported-by, of course.
Thanks,
Mauro
PATCH 5/6 scripts: kernel-doc: add support for typedef enum
In reply to Mauro Carvalho ChehabThe PHY kernel-doc markup has gained support for documenting a typedef enum.
However, right now the parser was not prepared for it.
So, add support for parsing it.
--- scripts/kernel-doc | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-)
scripts/kernel-doc +11 -4
@@ -1339,14 +1339,22 @@ sub show_warnings($$) { sub dump_enum($$) { my $x = shift; my $file = shift; + my $members; + $x =~ s@/\*.*?\*/@@gos; # strip comments. # strip #define macros inside enums $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos; - if ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) { + if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) { + $declaration_name = $2; + $members = $1; + } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) { $declaration_name = $1; - my $members = $2; + $members = $2; + } + + if ($declaration_name) { my %_members; $members =~ s/\s+$//;
@@ -1381,8 +1389,7 @@ sub dump_enum($$) { 'sections' => \%sections, 'purpose' => $declaration_purpose }); - } - else { + } else { print STDERR "${file}:$.: error: Cannot parse enum!\n"; ++$errors; }
Signature · 1 line
2.26.2
Re: [PATCH 5/6] scripts: kernel-doc: add support for typedef enum
Quoted 4 lines · Mauro Carvalho Chehab
The PHY kernel-doc markup has gained support for documenting a typedef enum.
However, right now the parser was not prepared for it.
Hi Mauro
Thanks for this. I'm using Sphinx 3.2.1, since that is what my Debian box has. So it can be hard to see the new warnings amongst the old.
Will this patch get merged via Jonathan Corbet's tree?
Thanks
Andrew
Re: [PATCH 5/6] scripts: kernel-doc: add support for typedef enum
Hi Andrew,
Em Fri, 2 Oct 2020 14:07:28 +0200
Andrew Lunn <[email protected]> escreveu:
Quoted 10 lines · Mauro Carvalho Chehab
Quoted 4 lines
The PHY kernel-doc markup has gained support for documenting a typedef enum.
However, right now the parser was not prepared for it.
Hi Mauro
Thanks for this. I'm using Sphinx 3.2.1, since that is what my Debian box has. So it can be hard to see the new warnings amongst the old.
Yeah, there were simply too much warnings with docs, and 3.2.1 is even worse.
Things will improve a lot after merging my set of patches fixing the issues for it. Yet, there are some warnings that can't currently be fixed on Sphinx 3.2 (~10 warnings). Fixing those will require some internal changes in Sphinx itself.
So, except if you need Sphinx 3 for some reason, I would suggest you to uninstall it, and then use venv with Sphinx 2.4.4. The Kernel build system should be able to provide you the commands for installing it, once you remove the one from your PATH.
Quoted 1 line
Will this patch get merged via Jonathan Corbet's tree?
Yes, that's the plan.
Thanks,
Mauro
PATCH 6/6 docs: gpio: add a new document to its index.rst
In reply to Mauro Carvalho ChehabThere's now a new ReST file. Add it to the index.rst file.
--- Documentation/admin-guide/gpio/index.rst | 1 + 1 file changed, 1 insertion(+)
Documentation/admin-guide/gpio/index.rst +1 -0
@@ -9,6 +9,7 @@ gpio gpio-aggregator sysfs + gpio-mockup .. only:: subproject and html
Signature · 1 line
2.26.2
Re: [PATCH 6/6] docs: gpio: add a new document to its index.rst
Quoted 22 lines · Mauro Carvalho Chehab
There's now a new ReST file. Add it to the
index.rstfile.Fixes ce7a2f77f976 ("docs: gpio: Add GPIO Aggregator documentation")Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/admin-guide/gpio/index.rst | 1 + 1 file changed, 1 insertion(+)Documentation/admin-guide/gpio/index.rst +1
-1@@ -9,6 +9,7 @@ gpio gpio-aggregator sysfs + gpio-mockup .. only:: subproject and html --
Quoted 2 lines
2.26.2
Good catch, thanks!
Re: [PATCH 6/6] docs: gpio: add a new document to its index.rst
In reply to Mauro Carvalho ChehabQuoted 3 lines · Mauro Carvalho Chehab
There's now a new ReST file. Add it to the
index.rstfile.Fixes ce7a2f77f976 ("docs: gpio: Add GPIO Aggregator documentation")
Shouldn't that be:
Cheers,
Kent.
Quoted 20 lines
Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/admin-guide/gpio/index.rst | 1 + 1 file changed, 1 insertion(+)Documentation/admin-guide/gpio/index.rst +1
-0@@ -9,6 +9,7 @@ gpio gpio-aggregator sysfs + gpio-mockup .. only:: subproject and htmlSignature · 1 line
2.26.2
Re: [PATCH 6/6] docs: gpio: add a new document to its index.rst
In reply to Mauro Carvalho ChehabQuoted 4 lines · Mauro Carvalho Chehab
There's now a new ReST file. Add it to the
index.rstfile.Fixes ce7a2f77f976 ("docs: gpio: Add GPIO Aggregator documentation")Signed-off-by Mauro Carvalho Chehab <[email protected]>
This patch (6/6) applied to the GPIO tree.
Fixed the Fixes: as indicated by Kent.
Yours,
Linus Walleij
Quoted 11 lines · Mauro Carvalho Chehab
There are some new warnings when building the documentation from yesterday's linux next. This small series fix them.
- patch 1 documents two new kernel-doc parameters on a net core file. I used the commit log in order to help documenting them;
- patch 2 fixes some tags at UMLv2 howto;
- patches 3 and 5 add some new documents at the corresponding index file.
- patch 4 changes kernel-doc script for it to recognize typedef enums.[...]
Applied to next, thanks!
[2/6] KVM: arm64: Fix some documentation build warnings
commit: 030bdf3698b7c3af190dd1fe714f0545f23441d0
Cheers,
M.
Signature · 1 line
Without deviation from the norm, progress is not possible.