Skip to contentSkip to conversation

Tree-wide nreferenced footnotes fixes

PATCH In review Bagas Sanjaya 5 participants 8 messages Jan 22, 2025 – Jan 23, 2025

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

cover Tree-wide nreferenced footnotes fixes

Sphinx 8.1 introduces improved unrefenced footnotes detector. The changelog
[1] reads:

- #12730: The UnreferencedFootnotesDetector transform has been improved to more consistently detect unreferenced footnotes. Note, the priority of the transform has been changed from 200 to 622, so that it now runs after the docutils Footnotes resolution transform. Patch by Chris Sewell.

As a result, a few new warnings are smoked out in the whole tree, that are previously unnoticed in earlier Sphinx versions. Let's squash these warnings.

[1]: https://lore.kernel.org/linux-next/[email protected]/

Bagas Sanjaya (3):
media: ipu3.rst: Prune unreferenced footnotes
Documentation: ublk: Drop Stefan Hajnoczi's message footnote
docs: power: Fix footnote reference for Toshiba Satellite P10-554

 Documentation/admin-guide/media/ipu3.rst | 7 ++-----
 Documentation/block/ublk.rst             | 2 --
 Documentation/power/video.rst            | 2 +-
 3 files changed, 3 insertions(+), 8 deletions(-)

base-commit: ffd294d346d185b70e28b1a28abe367bbfe53c04

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#1 lore raw

PATCH 1/3 media: ipu3.rst: Prune unreferenced footnotes

Sphinx reports unreferenced footnotes warning on ipu3 docs:

Documentation/admin-guide/media/ipu3.rst:592: WARNING: Footnote [#] is not referenced. [ref.footnote] Documentation/admin-guide/media/ipu3.rst:598: WARNING: Footnote [#] is not referenced. [ref.footnote]

Fix above warnings by pruning unreferenced footnote to intel_ipu3.h UAPI header (already referenced in its full path in "Running mode and firmware binary selection") and by directly link to v4l-utils repo in ov5670 configuration example with media-ctl (since the example is in literal code block).

Footnote numbers are unchanged.

Cc Rajmohan Mani <[email protected]>
Fixes dc794d3d2424 ("media: staging: ipu3-imgu: Move the UAPI header from include under include/uapi")
Fixes 34fc0e1bf892 ("media: doc-rst: Add Intel IPU3 documentation")
---
 Documentation/admin-guide/media/ipu3.rst | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)
Documentation/admin-guide/media/ipu3.rst +2 -5
index 83b3cd03b35c36..3a8c3d46304b7d 100644
@@ -98,7 +98,8 @@ frames in packed raw Bayer format to IPU3 CSI2 receiver.
     # and that ov5670 sensor is connected to i2c bus 10 with address 0x36
     export SDEV=$(media-ctl -d $MDEV -e "ov5670 10-0036")
 
-    # Establish the link for the media devices using media-ctl [#f3]_
+    # Establish the link for the media devices using media-ctl
+    # (from https://git.linuxtv.org/v4l-utils.git)
     media-ctl -d $MDEV -l "ov5670:0 -> ipu3-csi2 0:0[1]"
 
     # Set the format for the media devices
@@ -589,12 +590,8 @@ preserved.
 References
 ==========
 
-.. [#f5] drivers/staging/media/ipu3/include/uapi/intel-ipu3.h
-
 .. [#f1] https://github.com/intel/nvt
 
 .. [#f2] http://git.ideasonboard.org/yavta.git
 
-.. [#f3] http://git.ideasonboard.org/?p=media-ctl.git;a=summary
-
 .. [#f4] ImgU limitation requires an additional 16x16 for all input resolutions
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Reviewed-by on v1 1/3
#2 lore raw

RE: [PATCH 1/3] media: ipu3.rst: Prune unreferenced footnotes

Quoted 73 lines

-----Original Message-----
From: Bagas Sanjaya <[email protected]>
Sent: Wednesday, January 22, 2025 10:35 PM
To: Linux Media <[email protected]>; Linux Kernel Mailing List <[email protected]>; Linux Block Devices <linux- [email protected]>; Linux Documentation <[email protected]>; Linux Power Management <[email protected]>
Cc: Sakari Ailus <[email protected]>; Cao, Bingbu <[email protected]>; Qiu, Tian Shu <[email protected]>; Mauro Carvalho Chehab <[email protected]>; Ming Lei <[email protected]>; Jens Axboe <[email protected]>; Jonathan Corbet <[email protected]>; Rafael J. Wysocki <[email protected]>; Brown, Len <[email protected]>; Pavel Machek <[email protected]>; Bagas Sanjaya <[email protected]>; Rajmohan Mani <[email protected]>
Subject: [PATCH 1/3] media: ipu3.rst: Prune unreferenced footnotes

Sphinx reports unreferenced footnotes warning on ipu3 docs:

Documentation/admin-guide/media/ipu3.rst:592: WARNING: Footnote [#] is not referenced. [ref.footnote] Documentation/admin-guide/media/ipu3.rst:598: WARNING: Footnote [#] is not referenced. [ref.footnote]

Fix above warnings by pruning unreferenced footnote to intel_ipu3.h UAPI header (already referenced in its full path in "Running mode and firmware binary selection") and by directly link to v4l-utils repo in ov5670 configuration example with media-ctl (since the example is in literal code block).

Footnote numbers are unchanged.

Cc Rajmohan Mani <[email protected]>
Fixes dc794d3d2424 ("media: staging: ipu3-imgu: Move the UAPI header

from include under include/uapi")

Fixes 34fc0e1bf892 ("media: doc-rst: Add Intel IPU3 documentation")

---
Documentation/admin-guide/media/ipu3.rst | 7 ++-----

1 file changed, 2 insertions(+), 5 deletions(-)
Documentation/admin-guide/media/ipu3.rst +0 -0
index 83b3cd03b35c36..3a8c3d46304b7d 100644
@@ -98,7 +98,8 @@ frames in packed raw Bayer format to IPU3 CSI2

receiver.

    # and that ov5670 sensor is connected to i2c bus 10 with address
0x36
    export SDEV=$(media-ctl -d $MDEV -e "ov5670 10-0036")
Documentation/admin-guide/media/ipu3.rst +2 -1
-    # Establish the link for the media devices using media-ctl [#f3]_
+    # Establish the link for the media devices using media-ctl
+    # (from https://git.linuxtv.org/v4l-utils.git)
    media-ctl -d $MDEV -l "ov5670:0 -> ipu3-csi2 0:0[1]"
 
    # Set the format for the media devices @@ -589,12 +590,8 @@

preserved.
References
==========

-.. [#f5] drivers/staging/media/ipu3/include/uapi/intel-ipu3.h -
.. [#f1] https://github.com/intel/nvt

.. [#f2] http://git.ideasonboard.org/yavta.git

-.. [#f3] http://git.ideasonboard.org/?p=media-ctl.git;a=summary
-
.. [#f4] ImgU limitation requires an additional 16x16 for all input resolutions
--
An old man doll... just what I always wanted! - Clara

maintainer
#3 lore raw

Re: [PATCH 1/3] media: ipu3.rst: Prune unreferenced footnotes

In reply to Bagas Sanjaya

Hi Bagas,

Thanks for the patches.

Quoted 11 lines · Bagas Sanjaya

Sphinx reports unreferenced footnotes warning on ipu3 docs:

Documentation/admin-guide/media/ipu3.rst:592: WARNING: Footnote [#] is not referenced. [ref.footnote] Documentation/admin-guide/media/ipu3.rst:598: WARNING: Footnote [#] is not referenced. [ref.footnote]

Fix above warnings by pruning unreferenced footnote to intel_ipu3.h UAPI header (already referenced in its full path in "Running mode and firmware binary selection") and by directly link to v4l-utils repo in ov5670 configuration example with media-ctl (since the example is in literal code block).

Quoted 6 lines

Footnote numbers are unchanged.

Cc Rajmohan Mani <[email protected]>
Fixes dc794d3d2424 ("media: staging: ipu3-imgu: Move the UAPI header from include under include/uapi")
Fixes 34fc0e1bf892 ("media: doc-rst: Add Intel IPU3 documentation")

The issues fixed by this patch have already been fixed in commit 688c0a6907a7c6e6776f314195c10536f249b37f (in media tree).

Signature · 3 lines
Kind regards,

Sakari Ailus
#4 lore raw

PATCH 2/3 Documentation: ublk: Drop Stefan Hajnoczi's message footnote

In reply to Bagas Sanjaya

Sphinx reports unreferenced footnote warning pointing to ubd-control message by Stefan Hajnoczi [1]:

Documentation/block/ublk.rst:336: WARNING: Footnote [#] is not referenced. [ref.footnote]

Drop the footnote to squash above warning.

Cc Stefan Hajnoczi <[email protected]>
Fixes 7a3d2225f1ae ("Documentation: document ublk")
---
 Documentation/block/ublk.rst | 2 --
 1 file changed, 2 deletions(-)
Documentation/block/ublk.rst +0 -2
index 51665a3e6a50cd..1e0e7358e14a96 100644
@@ -333,6 +333,4 @@ References
 
 .. [#userspace_readme] https://github.com/ming1/ubdsrv/blob/master/README
 
-.. [#stefan] https://lore.kernel.org/linux-block/[email protected]/
-
 .. [#xiaoguang] https://lore.kernel.org/linux-block/[email protected]/
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Reviewed-by on v1 2/3
#5 lore raw

Re: [PATCH 2/3] Documentation: ublk: Drop Stefan Hajnoczi's message footnote

Quoted 9 lines · Bagas Sanjaya

Sphinx reports unreferenced footnote warning pointing to ubd-control message by Stefan Hajnoczi [1]:

Documentation/block/ublk.rst:336: WARNING: Footnote [#] is not referenced. [ref.footnote]

Drop the footnote to squash above warning.

Cc Stefan Hajnoczi <[email protected]>
Fixes 7a3d2225f1ae ("Documentation: document ublk")

The commit that introduced the unreferenced footnote was:

Fixes 4093cb5a0634 ("ublk_drv: add mechanism for supporting unprivileged ublk device")

Other than that:

Quoted 20 lines
---
 Documentation/block/ublk.rst | 2 --
 1 file changed, 2 deletions(-)
Documentation/block/ublk.rst +0 -2
index 51665a3e6a50cd..1e0e7358e14a96 100644
@@ -333,6 +333,4 @@ References
 
 .. [#userspace_readme] https://github.com/ming1/ubdsrv/blob/master/README
 
-.. [#stefan] https://lore.kernel.org/linux-block/[email protected]/
-
 .. [#xiaoguang] https://lore.kernel.org/linux-block/[email protected]/
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#6 lore raw

PATCH 3/3 docs: power: Fix footnote reference for Toshiba Satellite P10-554

In reply to Bagas Sanjaya

Sphinx reports unreferenced footnote warning on "Video issues with S3 resume" doc:

Documentation/power/video.rst:213: WARNING: Footnote [#] is not referenced. [ref.footnote]

Fix the warning by separating footnote reference for Toshiba Satellite P10-554 by a space.

Fixes 151f4e2bdc7a ("docs: power: convert docs to ReST and rename to *.rst")
---
 Documentation/power/video.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/power/video.rst +1 -1
index 337a2ba9f32f0f..8ab2458d130437 100644
@@ -190,7 +190,7 @@ Toshiba Portege 3020CT		s3_mode (3)
 Toshiba Satellite 4030CDT	s3_mode (3) (S1 also works OK)
 Toshiba Satellite 4080XCDT      s3_mode (3) (S1 also works OK)
 Toshiba Satellite 4090XCDT      ??? [#f1]_
-Toshiba Satellite P10-554       s3_bios,s3_mode (4)[#f3]_
+Toshiba Satellite P10-554       s3_bios,s3_mode (4) [#f3]_
 Toshiba M30                     (2) xor X with nvidia driver using internal AGP
 Uniwill 244IIO			??? [#f1]_
 =============================== ===============================================
Signature · 1 line
An old man doll... just what I always wanted! - Clara
maintainer
#7 lore raw
In reply to Bagas Sanjaya
Quoted 7 lines · Bagas Sanjaya

Sphinx 8.1 introduces improved unrefenced footnotes detector. The changelog
[1] reads:

- #12730: The UnreferencedFootnotesDetector transform has been improved to more consistently detect unreferenced footnotes. Note, the priority of the transform has been changed from 200 to 622, so that it now runs after the docutils Footnotes resolution transform. Patch by Chris Sewell.

Something they don't advertise so much, but should: this release also cuts the docs-build time almost in half for me. Very nice.

Quoted 11 lines

As a result, a few new warnings are smoked out in the whole tree, that are previously unnoticed in earlier Sphinx versions. Let's squash these warnings.

[1]: https://lore.kernel.org/linux-next/[email protected]/

Bagas Sanjaya (3):
media: ipu3.rst: Prune unreferenced footnotes
Documentation: ublk: Drop Stefan Hajnoczi's message footnote
docs: power: Fix footnote reference for Toshiba Satellite P10-554

Quoted 4 lines
 Documentation/admin-guide/media/ipu3.rst | 7 ++-----
 Documentation/block/ublk.rst             | 2 --
 Documentation/power/video.rst            | 2 +-
 3 files changed, 3 insertions(+), 8 deletions(-)

I'll apply these and ship them on up before the end of the merge window, thanks.

jon