Skip to contentSkip to conversation

Fix new html build warnings from next-20201001

PATCH Applied Mauro Carvalho Chehab 10 participants 18 messages Oct 2, 2020 – Oct 7, 2020

Subsystems (10)
lore
Share & tools
lore
#0 lore raw

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
#13 lore raw

PATCH 6/6 docs: gpio: add a new document to its index.rst

There's now a new ReST file. Add it to the index.rst file.

Fixes ce7a2f77f976 ("docs: gpio: Add GPIO Aggregator documentation")
---
 Documentation/admin-guide/gpio/index.rst | 1 +
 1 file changed, 1 insertion(+)
Documentation/admin-guide/gpio/index.rst +1 -0
index ef2838638e96..7db367572f30 100644
@@ -9,6 +9,7 @@ gpio
 
     gpio-aggregator
     sysfs
+    gpio-mockup
 
 .. only::  subproject and html
 
Signature · 1 line
2.26.2
#5 lore raw

PATCH 3/6 docs: virt: user_mode_linux_howto_v2.rst: fix a literal block markup

In reply to 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")
---
 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
index f70e6f5873c6..312e431695d9 100644
@@ -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
#7 lore raw

PATCH 4/6 docs: i2c: index.rst: add slave-testunit-backend.rst

In reply to Mauro Carvalho Chehab

As warned by Sphinx:

.../Documentation/i2c/slave-testunit-backend.rst: WARNING: document isn't included in any toctree

This document is not included anywhere.

Fixes a8335c64c5f0 ("i2c: add slave testunit driver")
---
 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
index adc4ecc72361..f794e2b1096c 100644
@@ -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
index 8a2ad3845191..9b8df313902c 100644
@@ -38,6 +38,7 @@ Debugging
 
    gpio-fault-injection
    i2c-stub
+   slave-testunit-backend
 
 Slave I2C
 =========
Signature · 1 line
2.26.2
#3 lore raw

PATCH 2/6 docs: vcpu.rst: fix some build warnings

In reply to 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")
---
 Documentation/virt/kvm/devices/vcpu.rst | 26 ++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)
Documentation/virt/kvm/devices/vcpu.rst +13 -13
index da7c2ef7dafc..2acec3b9ef65 100644
@@ -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
#1 lore raw

PATCH 1/6 net: core: document two new elements of struct net_device

In reply to Mauro Carvalho Chehab

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")
---
 include/linux/netdevice.h | 5 +++++
 1 file changed, 5 insertions(+)
include/linux/netdevice.h +5 -0
index 78880047907e..7852921480da 100644
@@ -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
#10 lore raw

PATCH 5/6 scripts: kernel-doc: add support for typedef enum

In reply to 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.

So, add support for parsing it.

Fixes 4069a572d423 ("net: phy: Document core PHY structures")
---
 scripts/kernel-doc | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)
scripts/kernel-doc +11 -4
index d94e28fcead0..5ac3749905e5 100755
@@ -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
maintainer Acked-by on v1 3/6
#6 lore raw

Re: [PATCH 3/6] docs: virt: user_mode_linux_howto_v2.rst: fix a literal block markup

In reply to Mauro Carvalho Chehab
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")
---
  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
index f70e6f5873c6..312e431695d9 100644

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/
#8 lore raw

Re: [PATCH 4/6] docs: i2c: index.rst: add slave-testunit-backend.rst

In reply to Mauro Carvalho Chehab

Hi Mauro,

Documentation/i2c/index.rst Debugging · line 41

Quoted 8 lines

index 8a2ad3845191..9b8df313902c 100644

Documentation/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

maintainer Acked-by on v1 2/6
#4 lore raw

Re: [PATCH 2/6] docs: vcpu.rst: fix some build warnings

In reply to Mauro Carvalho Chehab
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")
---
 Documentation/virt/kvm/devices/vcpu.rst | 26 ++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)
Documentation/virt/kvm/devices/vcpu.rst +10 -10
index da7c2ef7dafc..2acec3b9ef65 100644
@@ -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
maintainer Applied
#17 lore raw
In reply to Mauro Carvalho Chehab
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.
#9 lore raw

Re: [PATCH 4/6] docs: i2c: index.rst: add slave-testunit-backend.rst

In reply to Wolfram Sang

Em Fri, 2 Oct 2020 09:54:04 +0200
Wolfram Sang <[email protected]> escreveu:

Quoted 7 lines

Hi Mauro,

Quoted 5 lines

index 8a2ad3845191..9b8df313902c 100644

Documentation/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 -0
    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?

Yeah, sure!

Quoted 2 lines

I'd credit you with
Reported-by, of course.

Thanks,
Mauro

#11 lore raw

Re: [PATCH 5/6] scripts: kernel-doc: add support for typedef enum

In reply to Mauro Carvalho Chehab
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

Acked-by on v1 6/6
#14 lore raw

Re: [PATCH 6/6] docs: gpio: add a new document to its index.rst

In reply to Mauro Carvalho Chehab
Quoted 22 lines · Mauro Carvalho Chehab

There's now a new ReST file. Add it to the index.rst file.

Fixes ce7a2f77f976 ("docs: gpio: Add GPIO Aggregator documentation")
---
 Documentation/admin-guide/gpio/index.rst | 1 +
 1 file changed, 1 insertion(+)
Documentation/admin-guide/gpio/index.rst +1 -1
index ef2838638e96..7db367572f30 100644
@@ -9,6 +9,7 @@ gpio
 
     gpio-aggregator
     sysfs
+    gpio-mockup
 
 .. only::  subproject and html
 
--
Quoted 2 lines

2.26.2

Good catch, thanks!

maintainer Applied
#2 lore raw

Re: [PATCH 1/6] net: core: document two new elements of struct net_device

In reply to Mauro Carvalho Chehab

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")

Applied, thank you.

#15 lore raw

Re: [PATCH 6/6] docs: gpio: add a new document to its index.rst

In reply to Mauro Carvalho Chehab
Quoted 3 lines · Mauro Carvalho Chehab

There's now a new ReST file. Add it to the index.rst file.

Fixes ce7a2f77f976 ("docs: gpio: Add GPIO Aggregator documentation")

Shouldn't that be:

Fixes fd1abe99e5fb ("Documentation: gpio: add documentation for gpio-mockup")

Cheers,
Kent.

Quoted 20 lines
---
 Documentation/admin-guide/gpio/index.rst | 1 +
 1 file changed, 1 insertion(+)
Documentation/admin-guide/gpio/index.rst +1 -0
index ef2838638e96..7db367572f30 100644
@@ -9,6 +9,7 @@ gpio
 
     gpio-aggregator
     sysfs
+    gpio-mockup
 
 .. only::  subproject and html
 
Signature · 1 line
2.26.2
#12 lore raw

Re: [PATCH 5/6] scripts: kernel-doc: add support for typedef enum

In reply to Andrew Lunn

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