[PATCH v3 0/1] reproducible sphinx docs

[PATCH v3 0/1] reproducible sphinx docs

[Jelle]

From: Jelle van der Waa <jvanderwaa@redhat.com>

James Addison brought up this patch regarding reproducible kernel
documentation and I volunteered to re-send it as they have issues
setting up a MTA.

With this patch Arch Linux is able to succesfully when reproduce the
sphinx docs on a different machine.

James Addison (1):
  docs: Disambiguate a pair of rST labels

 Documentation/admin-guide/quickly-build-trimmed-linux.rst     | 4 ++--
 .../admin-guide/verify-bugs-and-bisect-regressions.rst        | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

-- 
2.49.0

[PATCH v3 1/1] docs: Disambiguate a pair of rST labels

[Jelle]

From: James Addison <jay@jp-hosting.net>

According to the reStructuredText documentation, internal hyperlink
targets[1] are intended to resolve within the current document.

Sphinx has a bug that causes internal hyperlinks declared with
duplicate names to resolve nondeterministically, producing incorrect
documentation. Sphinx does not yet emit a warning when these
duplicate target names are declared.

To improve the reproducibility and correctness of the HTML
documentation, disambiguate two labels both previously titled
"submit_improvements".

[1] - https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets

Link: https://github.com/sphinx-doc/sphinx/issues/13383
Signed-off-by: James Addison <jay@jp-hosting.net>
---
 Documentation/admin-guide/quickly-build-trimmed-linux.rst     | 4 ++--
 .../admin-guide/verify-bugs-and-bisect-regressions.rst        | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/admin-guide/quickly-build-trimmed-linux.rst b/Documentation/admin-guide/quickly-build-trimmed-linux.rst
index 07cfd8863b46..4a5ffb0996a3 100644
--- a/Documentation/admin-guide/quickly-build-trimmed-linux.rst
+++ b/Documentation/admin-guide/quickly-build-trimmed-linux.rst
@@ -347,7 +347,7 @@ again.
 
    [:ref:`details<uninstall>`]
 
-.. _submit_improvements:
+.. _submit_improvements_qbtl:
 
 Did you run into trouble following any of the above steps that is not cleared up
 by the reference section below? Or do you have ideas how to improve the text?
@@ -1070,7 +1070,7 @@ complicated, and harder to follow.
 
 That being said: this of course is a balancing act. Hence, if you think an
 additional use-case is worth describing, suggest it to the maintainers of this
-document, as :ref:`described above <submit_improvements>`.
+document, as :ref:`described above <submit_improvements_qbtl>`.
 
 
 ..
diff --git a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
index 03c55151346c..d8946b084b1e 100644
--- a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
+++ b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
@@ -267,7 +267,7 @@ culprit might be known already. For further details on what actually qualifies
 as a regression check out Documentation/admin-guide/reporting-regressions.rst.
 
 If you run into any problems while following this guide or have ideas how to
-improve it, :ref:`please let the kernel developers know <submit_improvements>`.
+improve it, :ref:`please let the kernel developers know <submit_improvements_vbbr>`.
 
 .. _introprep_bissbs:
 
@@ -1055,7 +1055,7 @@ follow these instructions.
 
 [:ref:`details <introoptional_bisref>`]
 
-.. _submit_improvements:
+.. _submit_improvements_vbbr:
 
 Conclusion
 ----------
-- 
2.49.0

Re: [PATCH v3 1/1] docs: Disambiguate a pair of rST labels

[Bagas Sanjaya]

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

[fixing Jelle's submission address]

On Mon, Apr 07, 2025 at 09:51:20PM +0200, JellevanderWaa wrote:
> diff --git a/Documentation/admin-guide/quickly-build-trimmed-linux.rst b/Documentation/admin-guide/quickly-build-trimmed-linux.rst
> index 07cfd8863b46..4a5ffb0996a3 100644
> --- a/Documentation/admin-guide/quickly-build-trimmed-linux.rst
> +++ b/Documentation/admin-guide/quickly-build-trimmed-linux.rst
> @@ -347,7 +347,7 @@ again.
>  
>     [:ref:`details<uninstall>`]
>  
> -.. _submit_improvements:
> +.. _submit_improvements_qbtl:
>  
>  Did you run into trouble following any of the above steps that is not cleared up
>  by the reference section below? Or do you have ideas how to improve the text?
> @@ -1070,7 +1070,7 @@ complicated, and harder to follow.
>  
>  That being said: this of course is a balancing act. Hence, if you think an
>  additional use-case is worth describing, suggest it to the maintainers of this
> -document, as :ref:`described above <submit_improvements>`.
> +document, as :ref:`described above <submit_improvements_qbtl>`.
>  
>  
>  ..
> diff --git a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
> index 03c55151346c..d8946b084b1e 100644
> --- a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
> +++ b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
> @@ -267,7 +267,7 @@ culprit might be known already. For further details on what actually qualifies
>  as a regression check out Documentation/admin-guide/reporting-regressions.rst.
>  
>  If you run into any problems while following this guide or have ideas how to
> -improve it, :ref:`please let the kernel developers know <submit_improvements>`.
> +improve it, :ref:`please let the kernel developers know <submit_improvements_vbbr>`.
>  
>  .. _introprep_bissbs:
>  
> @@ -1055,7 +1055,7 @@ follow these instructions.
>  
>  [:ref:`details <introoptional_bisref>`]
>  
> -.. _submit_improvements:
> +.. _submit_improvements_vbbr:
>  
>  Conclusion
>  ----------

LGTM, thanks!

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

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

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

Re: [PATCH v3 1/1] docs: Disambiguate a pair of rST labels

[James Addison]

On Tue, 8 Apr 2025 at 00:34, Bagas Sanjaya <bagasdotme@gmail.com> wrote:
> LGTM, thanks!
>
> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

Thank you, Bagas - and thank you too, Jelle, for forwarding the patch for me.

Re: [PATCH v3 1/1] docs: Disambiguate a pair of rST labels

[Jonathan Corbet]

Jelle van der Waa writes:

> From: James Addison <jay@jp-hosting.net>
>
> According to the reStructuredText documentation, internal hyperlink
> targets[1] are intended to resolve within the current document.
>
> Sphinx has a bug that causes internal hyperlinks declared with
> duplicate names to resolve nondeterministically, producing incorrect
> documentation. Sphinx does not yet emit a warning when these
> duplicate target names are declared.
>
> To improve the reproducibility and correctness of the HTML
> documentation, disambiguate two labels both previously titled
> "submit_improvements".
>
> [1] - https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets
>
> Link: https://github.com/sphinx-doc/sphinx/issues/13383
> Signed-off-by: James Addison <jay@jp-hosting.net>
> ---
>  Documentation/admin-guide/quickly-build-trimmed-linux.rst     | 4 ++--
>  .../admin-guide/verify-bugs-and-bisect-regressions.rst        | 4 ++--
>  2 files changed, 4 insertions(+), 4 deletions(-)

The patch makes sense, and I've applied it, but ...

- When you forward a patch like this, you are really supposed to add
  your own Signed-off-by tag to it.  Given the nature of the patch and
  the explicit acknowledgment from James, I've concluded I can proceed
  without it.

- The headers of this patch have:

	From: Jelle van der Waa

  ...which doesn't help in the generation of a proper reply.  Something
  to look into.

Thanks,

jon