[PATCH 0/3] Tree-wide nreferenced footnotes fixes

[PATCH 0/3] Tree-wide nreferenced footnotes fixes

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

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/07507296-a37b-4543-97cb-0560ef7fb7b8@gmail.com/

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
-- 
An old man doll... just what I always wanted! - Clara

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

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

Footnote numbers are unchanged.

Cc: Rajmohan Mani <rajmohan.mani@intel.com>
Fixes: dc794d3d2424 ("media: staging: ipu3-imgu: Move the UAPI header from include under include/uapi")
Fixes: 34fc0e1bf892 ("media: doc-rst: Add Intel IPU3 documentation")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/admin-guide/media/ipu3.rst | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/Documentation/admin-guide/media/ipu3.rst b/Documentation/admin-guide/media/ipu3.rst
index 83b3cd03b35c36..3a8c3d46304b7d 100644
--- a/Documentation/admin-guide/media/ipu3.rst
+++ b/Documentation/admin-guide/media/ipu3.rst
@@ -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
-- 
An old man doll... just what I always wanted! - Clara

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

[Cao, Bingbu]

Reviewed-by: Bingbu Cao <bingbu.cao@intel.com>

>-----Original Message-----
>From: Bagas Sanjaya <bagasdotme@gmail.com>
>Sent: Wednesday, January 22, 2025 10:35 PM
>To: Linux Media <linux-media@vger.kernel.org>; Linux Kernel Mailing
>List <linux-kernel@vger.kernel.org>; Linux Block Devices <linux-
>block@vger.kernel.org>; Linux Documentation <linux-doc@vger.kernel.org>;
>Linux Power Management <linux-pm@vger.kernel.org>
>Cc: Sakari Ailus <sakari.ailus@linux.intel.com>; Cao, Bingbu
><bingbu.cao@intel.com>; Qiu, Tian Shu <tian.shu.qiu@intel.com>; Mauro
>Carvalho Chehab <mchehab@kernel.org>; Ming Lei <ming.lei@redhat.com>;
>Jens Axboe <axboe@kernel.dk>; Jonathan Corbet <corbet@lwn.net>; Rafael
>J. Wysocki <rafael@kernel.org>; Brown, Len <len.brown@intel.com>; Pavel
>Machek <pavel@ucw.cz>; Bagas Sanjaya <bagasdotme@gmail.com>; Rajmohan
>Mani <rajmohan.mani@intel.com>
>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 <rajmohan.mani@intel.com>
>Fixes: dc794d3d2424 ("media: staging: ipu3-imgu: Move the UAPI header
>from include under include/uapi")
>Fixes: 34fc0e1bf892 ("media: doc-rst: Add Intel IPU3 documentation")
>Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
>---
> Documentation/admin-guide/media/ipu3.rst | 7 ++-----
> 1 file changed, 2 insertions(+), 5 deletions(-)
>
>diff --git a/Documentation/admin-guide/media/ipu3.rst
>b/Documentation/admin-guide/media/ipu3.rst
>index 83b3cd03b35c36..3a8c3d46304b7d 100644
>--- a/Documentation/admin-guide/media/ipu3.rst
>+++ b/Documentation/admin-guide/media/ipu3.rst
>@@ -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
>--
>An old man doll... just what I always wanted! - Clara

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

[Sakari Ailus]

Hi Bagas,

Thanks for the patches.

On Wed, Jan 22, 2025 at 09:34:54PM +0700, Bagas Sanjaya wrote:
> 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 <rajmohan.mani@intel.com>
> Fixes: dc794d3d2424 ("media: staging: ipu3-imgu: Move the UAPI header from include under include/uapi")
> Fixes: 34fc0e1bf892 ("media: doc-rst: Add Intel IPU3 documentation")
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

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

-- 
Kind regards,

Sakari Ailus

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

[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 <stefanha@redhat.com>
Fixes: 7a3d2225f1ae ("Documentation: document ublk")
Link: https://lore.kernel.org/linux-block/YoOr6jBfgVm8GvWg@stefanha-x1.localdomain/ [1]
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/block/ublk.rst | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Documentation/block/ublk.rst b/Documentation/block/ublk.rst
index 51665a3e6a50cd..1e0e7358e14a96 100644
--- a/Documentation/block/ublk.rst
+++ b/Documentation/block/ublk.rst
@@ -333,6 +333,4 @@ References
 
 .. [#userspace_readme] https://github.com/ming1/ubdsrv/blob/master/README
 
-.. [#stefan] https://lore.kernel.org/linux-block/YoOr6jBfgVm8GvWg@stefanha-x1.localdomain/
-
 .. [#xiaoguang] https://lore.kernel.org/linux-block/YoOr6jBfgVm8GvWg@stefanha-x1.localdomain/
-- 
An old man doll... just what I always wanted! - Clara

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

[Stefan Hajnoczi]

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

On Wed, Jan 22, 2025 at 09:34:55PM +0700, Bagas Sanjaya wrote:
> 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 <stefanha@redhat.com>
> 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:

Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>

> Link: https://lore.kernel.org/linux-block/YoOr6jBfgVm8GvWg@stefanha-x1.localdomain/ [1]
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/block/ublk.rst | 2 --
>  1 file changed, 2 deletions(-)
> 
> diff --git a/Documentation/block/ublk.rst b/Documentation/block/ublk.rst
> index 51665a3e6a50cd..1e0e7358e14a96 100644
> --- a/Documentation/block/ublk.rst
> +++ b/Documentation/block/ublk.rst
> @@ -333,6 +333,4 @@ References
>  
>  .. [#userspace_readme] https://github.com/ming1/ubdsrv/blob/master/README
>  
> -.. [#stefan] https://lore.kernel.org/linux-block/YoOr6jBfgVm8GvWg@stefanha-x1.localdomain/
> -
>  .. [#xiaoguang] https://lore.kernel.org/linux-block/YoOr6jBfgVm8GvWg@stefanha-x1.localdomain/
> -- 
> An old man doll... just what I always wanted! - Clara
> 

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

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

[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")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/linux-next/20250122170335.148a23b0@canb.auug.org.au/
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/power/video.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/power/video.rst b/Documentation/power/video.rst
index 337a2ba9f32f0f..8ab2458d130437 100644
--- a/Documentation/power/video.rst
+++ b/Documentation/power/video.rst
@@ -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]_
 =============================== ===============================================
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 0/3] Tree-wide nreferenced footnotes fixes

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

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

> 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/07507296-a37b-4543-97cb-0560ef7fb7b8@gmail.com/
>
> 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(-)

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

jon