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

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