[PATCH 00/12] Fix several documentation build warnings with Sphinx 2.4.4

[PATCH 00/12] Fix several documentation build warnings with Sphinx 2.4.4

[Mauro Carvalho Chehab]

This series is against next-20220701. It fixes several warnings
that are currently produced while building html docs.

Each patch in this series is independent from the others, as
each one touches a different file.

Mauro Carvalho Chehab (12):
  docs: ext4: blockmap.rst: fix a broken table
  docs: tegra194-hte.rst: don't include gpiolib.c twice
  docs: device-mapper: add a blank line at writecache.rst
  docs: PCI: pci-vntb-function.rst: Properly include ascii artwork
  docs: PCI: pci-vntb-howto.rst: fix a title markup
  docs: virt: kvm: fix a title markup at api.rst
  docs: ABI: sysfs-bus-nvdimm
  kunit: test.h: fix a kernel-doc markup
  net: mac80211: fix a kernel-doc markup
  docs: alsa: alsa-driver-api.rst: remove a kernel-doc file
  docs: arm: index.rst: add google/chromebook-boot-flow
  docs: leds: index.rst: add leds-qcom-lpg to it

 Documentation/ABI/testing/sysfs-bus-nvdimm             | 2 ++
 Documentation/PCI/endpoint/pci-vntb-function.rst       | 2 +-
 Documentation/PCI/endpoint/pci-vntb-howto.rst          | 2 +-
 Documentation/admin-guide/device-mapper/writecache.rst | 1 +
 Documentation/arm/index.rst                            | 2 ++
 Documentation/driver-api/hte/tegra194-hte.rst          | 3 +--
 Documentation/filesystems/ext4/blockmap.rst            | 2 +-
 Documentation/leds/index.rst                           | 1 +
 Documentation/sound/kernel-api/alsa-driver-api.rst     | 1 -
 Documentation/virt/kvm/api.rst                         | 6 +++---
 include/kunit/test.h                                   | 2 +-
 include/net/mac80211.h                                 | 2 +-
 12 files changed, 15 insertions(+), 11 deletions(-)

-- 
2.36.1

[PATCH 08/12] kunit: test.h: fix a kernel-doc markup

[Mauro Carvalho Chehab]

Fix this kernel-doc warning:

	Documentation/dev-tools/kunit/api/test:9: ./include/kunit/test.h:323: WARNING: Inline interpreted text or phrase reference start-string without end-string.

Functions should use func_name() on kernel-doc markups, as
documented at:
	Documentation/doc-guide/kernel-doc.rst

Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH 00/12] at: https://lore.kernel.org/all/cover.1656759988.git.mchehab@kernel.org/

 include/kunit/test.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/kunit/test.h b/include/kunit/test.h
index 8ffcd7de9607..f1c1a95df9b8 100644
--- a/include/kunit/test.h
+++ b/include/kunit/test.h
@@ -320,7 +320,7 @@ static inline int kunit_run_all_tests(void)
  *
  * @__suites: a statically allocated list of &struct kunit_suite.
  *
- * This functions identically as &kunit_test_suites() except that it suppresses
+ * This functions identically as kunit_test_suites() except that it suppresses
  * modpost warnings for referencing functions marked __init or data marked
  * __initdata; this is OK because currently KUnit only runs tests upon boot
  * during the init phase or upon loading a module during the init phase.
-- 
2.36.1

Re: [PATCH 08/12] kunit: test.h: fix a kernel-doc markup

[David Gow]

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

On Sat, Jul 2, 2022 at 7:07 PM Mauro Carvalho Chehab <mchehab@kernel.org> wrote:
>
> Fix this kernel-doc warning:
>
>         Documentation/dev-tools/kunit/api/test:9: ./include/kunit/test.h:323: WARNING: Inline interpreted text or phrase reference start-string without end-string.
>
> Functions should use func_name() on kernel-doc markups, as
> documented at:
>         Documentation/doc-guide/kernel-doc.rst
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
>
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH 00/12] at: https://lore.kernel.org/all/cover.1656759988.git.mchehab@kernel.org/
>

Reviewed-by: David Gow <davidgow@google.com>

FYI, this is identical to:
https://lore.kernel.org/all/20220702051205.3292468-1-davidgow@google.com/

It doesn't matter which one goes through, so if this patch is applied
(e.g. to the docs tree as a part of this series), I'll make sure the
other one doesn't end up in the KUnit tree.

Cheers,
-- David

>  include/kunit/test.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/include/kunit/test.h b/include/kunit/test.h
> index 8ffcd7de9607..f1c1a95df9b8 100644
> --- a/include/kunit/test.h
> +++ b/include/kunit/test.h
> @@ -320,7 +320,7 @@ static inline int kunit_run_all_tests(void)
>   *
>   * @__suites: a statically allocated list of &struct kunit_suite.
>   *
> - * This functions identically as &kunit_test_suites() except that it suppresses
> + * This functions identically as kunit_test_suites() except that it suppresses
>   * modpost warnings for referencing functions marked __init or data marked
>   * __initdata; this is OK because currently KUnit only runs tests upon boot
>   * during the init phase or upon loading a module during the init phase.
> --
> 2.36.1
>
> --
> You received this message because you are subscribed to the Google Groups "KUnit Development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to kunit-dev+unsubscribe@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/kunit-dev/32a67e9ee77cc6c435d08a2cb5ef12559b417fee.1656759989.git.mchehab%40kernel.org.

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 4003 bytes --]

Re: [PATCH 00/12] Fix several documentation build warnings with Sphinx 2.4.4

[Bagas Sanjaya]

On Sat, Jul 02, 2022 at 12:07:32PM +0100, Mauro Carvalho Chehab wrote:
> This series is against next-20220701. It fixes several warnings
> that are currently produced while building html docs.
> 
> Each patch in this series is independent from the others, as
> each one touches a different file.
> 
> Mauro Carvalho Chehab (12):
>   docs: ext4: blockmap.rst: fix a broken table
>   docs: tegra194-hte.rst: don't include gpiolib.c twice
>   docs: device-mapper: add a blank line at writecache.rst
>   docs: PCI: pci-vntb-function.rst: Properly include ascii artwork
>   docs: PCI: pci-vntb-howto.rst: fix a title markup
>   docs: virt: kvm: fix a title markup at api.rst
>   docs: ABI: sysfs-bus-nvdimm
>   kunit: test.h: fix a kernel-doc markup
>   net: mac80211: fix a kernel-doc markup
>   docs: alsa: alsa-driver-api.rst: remove a kernel-doc file
>   docs: arm: index.rst: add google/chromebook-boot-flow
>   docs: leds: index.rst: add leds-qcom-lpg to it
> 

Hi Mauro,

Thanks for cleaning up these warning above. However, I have already
submitted some of these cleanups (pending reviews or integration):

[1]: https://lore.kernel.org/linux-doc/20220702042350.23187-1-bagasdotme@gmail.com/
[2]: https://lore.kernel.org/linux-doc/20220612000125.9777-1-bagasdotme@gmail.com/
[3]: https://lore.kernel.org/linux-doc/20220627095151.19339-1-bagasdotme@gmail.com/
[4]: https://lore.kernel.org/linux-doc/20220627082928.11239-1-bagasdotme@gmail.com/

There's still a warning left:

Documentation/ABI/testing/sysfs-bus-iio-sx9324:2: WARNING: Unexpected indentation.

But I think the Date: field that triggered the warning above looks OK.

Regardless of that, the build successed.

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 08/12] kunit: test.h: fix a kernel-doc markup

[Shuah Khan]

On 7/2/22 7:18 AM, David Gow wrote:
> On Sat, Jul 2, 2022 at 7:07 PM Mauro Carvalho Chehab <mchehab@kernel.org> wrote:
>>
>> Fix this kernel-doc warning:
>>
>>          Documentation/dev-tools/kunit/api/test:9: ./include/kunit/test.h:323: WARNING: Inline interpreted text or phrase reference start-string without end-string.
>>
>> Functions should use func_name() on kernel-doc markups, as
>> documented at:
>>          Documentation/doc-guide/kernel-doc.rst
>>
>> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
>> ---
>>
>> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
>> See [PATCH 00/12] at: https://lore.kernel.org/all/cover.1656759988.git.mchehab@kernel.org/
>>
> 
> Reviewed-by: David Gow <davidgow@google.com>
> 
> FYI, this is identical to:
> https://lore.kernel.org/all/20220702051205.3292468-1-davidgow@google.com/
> 
> It doesn't matter which one goes through, so if this patch is applied
> (e.g. to the docs tree as a part of this series), I'll make sure the
> other one doesn't end up in the KUnit tree.
> 
> Cheers,
> -- David
> 

Applied this now to linux-kselftest kunit branch for 5.20-rc1

thanks,
-- Shuah