[PATCH 0/6] Fix new html build warnings from next-20201001

[PATCH 0/6] Fix new html build warnings from next-20201001

[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.

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

-- 
2.26.2

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

[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 <mchehab+huawei@kernel.org>
---
 Documentation/virt/kvm/devices/vcpu.rst | 26 ++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/Documentation/virt/kvm/devices/vcpu.rst b/Documentation/virt/kvm/devices/vcpu.rst
index da7c2ef7dafc..2acec3b9ef65 100644
--- a/Documentation/virt/kvm/devices/vcpu.rst
+++ b/Documentation/virt/kvm/devices/vcpu.rst
@@ -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
-- 
2.26.2

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

[Paolo Bonzini]

On 02/10/20 07:49, Mauro Carvalho Chehab wrote:
> 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 <mchehab+huawei@kernel.org>
> ---
>  Documentation/virt/kvm/devices/vcpu.rst | 26 ++++++++++++-------------
>  1 file changed, 13 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/virt/kvm/devices/vcpu.rst b/Documentation/virt/kvm/devices/vcpu.rst
> index da7c2ef7dafc..2acec3b9ef65 100644
> --- a/Documentation/virt/kvm/devices/vcpu.rst
> +++ b/Documentation/virt/kvm/devices/vcpu.rst
> @@ -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
> 

Acked-by: Paolo Bonzini <pbonzini@redhat.com>

Re: [PATCH 0/6] Fix new html build warnings from next-20201001

[Marc Zyngier]

On Fri, 2 Oct 2020 07:49:44 +0200, Mauro Carvalho Chehab wrote:
> 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.
-- 
Without deviation from the norm, progress is not possible.