[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 4/6] docs: i2c: index.rst: add slave-testunit-backend.rst

[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")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/hw-vuln/l1d_flush.rst | 3 +--
 Documentation/i2c/index.rst                     | 1 +
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/admin-guide/hw-vuln/l1d_flush.rst b/Documentation/admin-guide/hw-vuln/l1d_flush.rst
index adc4ecc72361..f794e2b1096c 100644
--- a/Documentation/admin-guide/hw-vuln/l1d_flush.rst
+++ b/Documentation/admin-guide/hw-vuln/l1d_flush.rst
@@ -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.
diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
index 8a2ad3845191..9b8df313902c 100644
--- a/Documentation/i2c/index.rst
+++ b/Documentation/i2c/index.rst
@@ -38,6 +38,7 @@ Debugging
 
    gpio-fault-injection
    i2c-stub
+   slave-testunit-backend
 
 Slave I2C
 =========
-- 
2.26.2

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

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 498 bytes --]

Hi Mauro,

> index 8a2ad3845191..9b8df313902c 100644
> --- a/Documentation/i2c/index.rst
> +++ b/Documentation/i2c/index.rst
> @@ -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


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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.

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

[Mauro Carvalho Chehab]

Em Fri, 2 Oct 2020 09:54:04 +0200
Wolfram Sang <wsa@kernel.org> escreveu:

> Hi Mauro,
> 
> > index 8a2ad3845191..9b8df313902c 100644
> > --- a/Documentation/i2c/index.rst
> > +++ b/Documentation/i2c/index.rst
> > @@ -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?

Yeah, sure!

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

Thanks,
Mauro