[PATCH 00/12] Fix several documentation build warnings with Sphinx 2.4.4
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(-)
This file: sound/core/compress_offload.c
Doesn't define any docs, as everything is inside the header file. So, drop it, in order to remove a Sphinx warning.
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/
Documentation/sound/kernel-api/alsa-driver-api.rst | 1 - 1 file changed, 1 deletion(-)
diff --git a/Documentation/sound/kernel-api/alsa-driver-api.rst b/Documentation/sound/kernel-api/alsa-driver-api.rst index d24c64df7069..3cf8eb4ecaf4 100644 --- a/Documentation/sound/kernel-api/alsa-driver-api.rst +++ b/Documentation/sound/kernel-api/alsa-driver-api.rst @@ -86,7 +86,6 @@ Compress Offload
Compress Offload API -------------------- -.. kernel-doc:: sound/core/compress_offload.c .. kernel-doc:: include/uapi/sound/compress_offload.h .. kernel-doc:: include/uapi/sound/compress_params.h .. kernel-doc:: include/sound/compress_driver.h
On Sat, 02 Jul 2022 13:07:42 +0200, Mauro Carvalho Chehab wrote:
This file: sound/core/compress_offload.c
Doesn't define any docs, as everything is inside the header file. So, drop it, in order to remove a Sphinx warning.
Signed-off-by: Mauro Carvalho Chehab mchehab@kernel.org
Hmm, it looks rather like that some comments (at least for exported functions) should be marked with kerneldoc markers instead.
I'm going to fix those comments.
thanks,
Takashi
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/
Documentation/sound/kernel-api/alsa-driver-api.rst | 1 - 1 file changed, 1 deletion(-)
diff --git a/Documentation/sound/kernel-api/alsa-driver-api.rst b/Documentation/sound/kernel-api/alsa-driver-api.rst index d24c64df7069..3cf8eb4ecaf4 100644 --- a/Documentation/sound/kernel-api/alsa-driver-api.rst +++ b/Documentation/sound/kernel-api/alsa-driver-api.rst @@ -86,7 +86,6 @@ Compress Offload
Compress Offload API
-.. kernel-doc:: sound/core/compress_offload.c .. kernel-doc:: include/uapi/sound/compress_offload.h .. kernel-doc:: include/uapi/sound/compress_params.h .. kernel-doc:: include/sound/compress_driver.h -- 2.36.1
Em Mon, 04 Jul 2022 14:54:19 +0200 Takashi Iwai tiwai@suse.de escreveu:
On Sat, 02 Jul 2022 13:07:42 +0200, Mauro Carvalho Chehab wrote:
This file: sound/core/compress_offload.c
Doesn't define any docs, as everything is inside the header file. So, drop it, in order to remove a Sphinx warning.
Signed-off-by: Mauro Carvalho Chehab mchehab@kernel.org
Hmm, it looks rather like that some comments (at least for exported functions) should be marked with kerneldoc markers instead.
I'm going to fix those comments.
Go for it: adding kerneldoc markers is indeed a better solution :-)
Regards, Mauro
thanks,
Takashi
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/
Documentation/sound/kernel-api/alsa-driver-api.rst | 1 - 1 file changed, 1 deletion(-)
diff --git a/Documentation/sound/kernel-api/alsa-driver-api.rst b/Documentation/sound/kernel-api/alsa-driver-api.rst index d24c64df7069..3cf8eb4ecaf4 100644 --- a/Documentation/sound/kernel-api/alsa-driver-api.rst +++ b/Documentation/sound/kernel-api/alsa-driver-api.rst @@ -86,7 +86,6 @@ Compress Offload
Compress Offload API
-.. kernel-doc:: sound/core/compress_offload.c .. kernel-doc:: include/uapi/sound/compress_offload.h .. kernel-doc:: include/uapi/sound/compress_params.h .. kernel-doc:: include/sound/compress_driver.h -- 2.36.1
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.co... [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.co... [4]: https://lore.kernel.org/linux-doc/20220627082928.11239-1-bagasdotme@gmail.co...
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
participants (3)
-
Bagas Sanjaya
-
Mauro Carvalho Chehab
-
Takashi Iwai