[PATCH] docs: Disambiguate a pair of rST labels

[PATCH] docs: Disambiguate a pair of rST labels

[James Addison]

Because reStructuredText does not provide lexical scoping rules for
labels, resolution of targets that have duplicate declarations is
ambiguous and produces nondeterministic output.

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

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 07cfd8863..2d1b6f750 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_trimmed_build_improvements:

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


 ..
diff --git a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
index 03c551513..1b246d8a8 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_regression_tracing_improvements>`.

 .. _introprep_bissbs:

@@ -1055,7 +1055,7 @@ follow these instructions.

 [:ref:`details <introoptional_bisref>`]

-.. _submit_improvements:
+.. _submit_regression_tracing_improvements:

 Conclusion
 ----------
-- 
2.47.2

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

[Bagas Sanjaya]

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

On Sat, Feb 22, 2025 at 10:59:39PM +0000, James Addison wrote:
> diff --git a/Documentation/admin-guide/quickly-build-trimmed-linux.rst
> b/Documentation/admin-guide/quickly-build-trimmed-linux.rst
> index 07cfd8863..2d1b6f750 100644

Looks like your email client mangles the patch (the header above should
not split). Please resend, preferably with git-send-email(1).

Thanks.

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

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

[v2 0/1] reproducible sphinx docs

[Jelle van der Waa]

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 building on the
same machine, without this patch it is currently not reproducible see
the link below:

https://reproducible.archlinux.org/api/v0/builds/742727/diffoscope

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

Re: [v2 0/1] reproducible sphinx docs

[Bagas Sanjaya]

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

On Wed, Feb 26, 2025 at 09:34:50PM +0100, Jelle van der Waa wrote:
> 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.

Thank you for forwarding the patch! I might have to send my own version
otherwise.

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

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

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

[Jelle van der Waa]

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>

---
V1 -> V2: re-send using different email client
---
 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..2d1b6f7504c1 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_trimmed_build_improvements:
 
 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_trimmed_build_improvements>`.
 
 
 ..
diff --git a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
index 03c55151346c..1b246d8a8afb 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_regression_tracing_improvements>`.
 
 .. _introprep_bissbs:
 
@@ -1055,7 +1055,7 @@ follow these instructions.
 
 [:ref:`details <introoptional_bisref>`]
 
-.. _submit_improvements:
+.. _submit_regression_tracing_improvements:
 
 Conclusion
 ----------
-- 
2.48.1

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

[Bagas Sanjaya]

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

[Cc'ing Thorsten and Jon]

On Wed, Feb 26, 2025 at 09:34:51PM +0100, Jelle van der Waa wrote:
> 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".

On docs.kernel.org, I click "described above" link on quickly build kernel
guide [1] which takes me to bisection guide instead [2]. Now with this
patch, the same link now points to suggestions and improvements on the
same page.

[1]: https://docs.kernel.org/admin-guide/quickly-build-trimmed-linux.html
[2]: https://docs.kernel.org/admin-guide/verify-bugs-and-bisect-regressions.html#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>
> 
> ---
> V1 -> V2: re-send using different email client
> ---
>  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..2d1b6f7504c1 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_trimmed_build_improvements:
>  
>  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_trimmed_build_improvements>`.
>  
>  
>  ..
> diff --git a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
> index 03c55151346c..1b246d8a8afb 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_regression_tracing_improvements>`.
>  
>  .. _introprep_bissbs:
>  
> @@ -1055,7 +1055,7 @@ follow these instructions.
>  
>  [:ref:`details <introoptional_bisref>`]
>  
> -.. _submit_improvements:
> +.. _submit_regression_tracing_improvements:
>  
>  Conclusion
>  ----------

The patch itself looks good.

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

Thanks.

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

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

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

[Thorsten Leemhuis]

On 26.02.25 21:34, Jelle van der Waa wrote:
> 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>
> 
> ---
> V1 -> V2: re-send using different email client

Many thx for looking into this. FWIW, next time please run
./scripts/get_maintainer.pl and then ensure to add the maintainers of
the modified files to the list of recipients.

> ---
>  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..2d1b6f7504c1 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_trimmed_build_improvements:

Hmm. Does not matter much, but adding that "trimmed_build" in the middle
feels quite a bit odd to me. I recently in a similar situation added a
short suffix; here it could be "_qbtl", which is derived from the
initials of the file modified. I'd say that is a lot better, but using
something longer is fine for me as well, especially if it's only needed
in one or two places.

>  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_trimmed_build_improvements>`.
>  
>  
>  ..
> diff --git a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
> index 03c55151346c..1b246d8a8afb 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_regression_tracing_improvements>`.
>  
>  .. _introprep_bissbs:
>  
> @@ -1055,7 +1055,7 @@ follow these instructions.
>  
>  [:ref:`details <introoptional_bisref>`]
>  
> -.. _submit_improvements:
> +.. _submit_regression_tracing_improvements:

Same here with a different suffix.

Ciao, Thorsten