Re: [PATCH] Documentation: pm: fix duplicate hyperlink target errors

Re: [PATCH] Documentation: pm: fix duplicate hyperlink target errors

[Bagas Sanjaya]

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

On Wed, Oct 29, 2025 at 01:47:37PM +0000, Swaraj Gaikwad wrote:
> Fix reST warnings in
> Documentation/admin-guide/pm/intel_pstate.rst caused by missing explicit
> hyperlink labels for section titles.
> 
> Before this change, the following errors were printed during
> `make htmldocs`:
> 
>   Documentation/admin-guide/pm/intel_pstate.rst:401:
>     ERROR: Indirect hyperlink target (id="id6") refers to target
>     "passive mode", which is a duplicate, and cannot be used as a
>     unique reference.
>   Documentation/admin-guide/pm/intel_pstate.rst:517:
>     ERROR: Indirect hyperlink target (id="id9") refers to target
>     "active mode", which is a duplicate, and cannot be used as a
>     unique reference.
>   Documentation/admin-guide/pm/intel_pstate.rst:611:
>     ERROR: Indirect hyperlink target (id="id15") refers to target
>     "global attributes", which is a duplicate, and cannot be used as
>     a unique reference.
>   ERROR: Duplicate target name, cannot be used as a unique reference:
>   "passive mode", "active mode", "global attributes".

Hmm... I don't see these warnings when I build htmldocs by:

  $ make SPHINXOPTS='-j 1' htmldocs

My environment uses docutils 0.21.2 and Sphinx 8.2.3, though. What are yours?

> diff --git a/Documentation/admin-guide/pm/intel_pstate.rst b/Documentation/admin-guide/pm/intel_pstate.rst
> index 26e702c7016e..9cdd9dad6516 100644
> --- a/Documentation/admin-guide/pm/intel_pstate.rst
> +++ b/Documentation/admin-guide/pm/intel_pstate.rst
> @@ -62,6 +62,8 @@ a certain performance scaling algorithm.  Which of them will be in effect
>  depends on what kernel command line options are used and on the capabilities of
>  the processor.
> 
> +.. _Active Mode:
> +
>  Active Mode
>  -----------
> 
> @@ -94,6 +96,8 @@ Which of the P-state selection algorithms is used by default depends on the
>  Namely, if that option is set, the ``performance`` algorithm will be used by
>  default, and the other one will be used by default if it is not set.
> 
> +.. _Active Mode With HWP:
> +
>  Active Mode With HWP
>  ~~~~~~~~~~~~~~~~~~~~
> 
> @@ -192,6 +196,8 @@ This is the default P-state selection algorithm if the
>  :c:macro:`CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE` kernel configuration option
>  is not set.
> 
> +.. _Passive Mode:
> +
>  Passive Mode
>  ------------
> 
> @@ -432,6 +438,8 @@ the ``energy_model`` directory in ``debugfs`` (typlically mounted on
>  User Space Interface in ``sysfs``
>  =================================
> 
> +.. _Global Attributes:
> +
>  Global Attributes
>  -----------------
> 
> 

The diff LGTM, nevertheless.

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

[PATCH] Documentation: pm: fix duplicate hyperlink target errors

[Swaraj Gaikwad]

Fix reST warnings in
Documentation/admin-guide/pm/intel_pstate.rst caused by missing explicit
hyperlink labels for section titles.

Before this change, the following errors were printed during
`make htmldocs`:

  Documentation/admin-guide/pm/intel_pstate.rst:401:
    ERROR: Indirect hyperlink target (id="id6") refers to target
    "passive mode", which is a duplicate, and cannot be used as a
    unique reference.
  Documentation/admin-guide/pm/intel_pstate.rst:517:
    ERROR: Indirect hyperlink target (id="id9") refers to target
    "active mode", which is a duplicate, and cannot be used as a
    unique reference.
  Documentation/admin-guide/pm/intel_pstate.rst:611:
    ERROR: Indirect hyperlink target (id="id15") refers to target
    "global attributes", which is a duplicate, and cannot be used as
    a unique reference.
  ERROR: Duplicate target name, cannot be used as a unique reference:
  "passive mode", "active mode", "global attributes".

These errors occurred because the sections "Active Mode",
"Active Mode With HWP", "Passive Mode", and "Global Attributes"
did not define explicit hyperlink labels. As a result, Sphinx
auto-generated duplicate anchors when the same titles appeared
multiple times within the document.

Because of this, the generated HTML documentation contained
broken references such as:

  `active mode <Active Mode_>`_
  `passive mode <Passive Mode_>`_
  `global attributes <Global Attributes_>`_

This patch adds explicit hyperlink labels for the affected sections,
ensuring all references are unique and correctly resolved.

After applying this patch, `make htmldocs` completes without
any warnings, and all hyperlinks in intel_pstate.html render properly.


Signed-off-by: Swaraj Gaikwad <swarajgaikwad1925@gmail.com>
---
 Documentation/admin-guide/pm/intel_pstate.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/admin-guide/pm/intel_pstate.rst b/Documentation/admin-guide/pm/intel_pstate.rst
index 26e702c7016e..9cdd9dad6516 100644
--- a/Documentation/admin-guide/pm/intel_pstate.rst
+++ b/Documentation/admin-guide/pm/intel_pstate.rst
@@ -62,6 +62,8 @@ a certain performance scaling algorithm.  Which of them will be in effect
 depends on what kernel command line options are used and on the capabilities of
 the processor.

+.. _Active Mode:
+
 Active Mode
 -----------

@@ -94,6 +96,8 @@ Which of the P-state selection algorithms is used by default depends on the
 Namely, if that option is set, the ``performance`` algorithm will be used by
 default, and the other one will be used by default if it is not set.

+.. _Active Mode With HWP:
+
 Active Mode With HWP
 ~~~~~~~~~~~~~~~~~~~~

@@ -192,6 +196,8 @@ This is the default P-state selection algorithm if the
 :c:macro:`CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE` kernel configuration option
 is not set.

+.. _Passive Mode:
+
 Passive Mode
 ------------

@@ -432,6 +438,8 @@ the ``energy_model`` directory in ``debugfs`` (typlically mounted on
 User Space Interface in ``sysfs``
 =================================

+.. _Global Attributes:
+
 Global Attributes
 -----------------


base-commit: f30d294530d939fa4b77d61bc60f25c4284841fa
--
2.51.1

Re: [PATCH] Documentation: pm: fix duplicate hyperlink target errors

[Randy Dunlap]

On 10/29/25 3:55 AM, Bagas Sanjaya wrote:
> On Wed, Oct 29, 2025 at 01:47:37PM +0000, Swaraj Gaikwad wrote:
>> Fix reST warnings in
>> Documentation/admin-guide/pm/intel_pstate.rst caused by missing explicit
>> hyperlink labels for section titles.
>>
>> Before this change, the following errors were printed during
>> `make htmldocs`:
>>
>>   Documentation/admin-guide/pm/intel_pstate.rst:401:
>>     ERROR: Indirect hyperlink target (id="id6") refers to target
>>     "passive mode", which is a duplicate, and cannot be used as a
>>     unique reference.
>>   Documentation/admin-guide/pm/intel_pstate.rst:517:
>>     ERROR: Indirect hyperlink target (id="id9") refers to target
>>     "active mode", which is a duplicate, and cannot be used as a
>>     unique reference.
>>   Documentation/admin-guide/pm/intel_pstate.rst:611:
>>     ERROR: Indirect hyperlink target (id="id15") refers to target
>>     "global attributes", which is a duplicate, and cannot be used as
>>     a unique reference.
>>   ERROR: Duplicate target name, cannot be used as a unique reference:
>>   "passive mode", "active mode", "global attributes".
> 
> Hmm... I don't see these warnings when I build htmldocs by:
> 
>   $ make SPHINXOPTS='-j 1' htmldocs
> 
> My environment uses docutils 0.21.2 and Sphinx 8.2.3, though. What are yours?


I do see the warnings and this patch fixes them in my testing.

Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

docutils-3.13 (Docutils 0.22.2, Python 3.13.9, on linux)
sphinx-build 8.2.3

>> diff --git a/Documentation/admin-guide/pm/intel_pstate.rst b/Documentation/admin-guide/pm/intel_pstate.rst
>> index 26e702c7016e..9cdd9dad6516 100644
>> --- a/Documentation/admin-guide/pm/intel_pstate.rst
>> +++ b/Documentation/admin-guide/pm/intel_pstate.rst
>> @@ -62,6 +62,8 @@ a certain performance scaling algorithm.  Which of them will be in effect
>>  depends on what kernel command line options are used and on the capabilities of
>>  the processor.
>>
>> +.. _Active Mode:
>> +
>>  Active Mode
>>  -----------
>>
>> @@ -94,6 +96,8 @@ Which of the P-state selection algorithms is used by default depends on the
>>  Namely, if that option is set, the ``performance`` algorithm will be used by
>>  default, and the other one will be used by default if it is not set.
>>
>> +.. _Active Mode With HWP:
>> +
>>  Active Mode With HWP
>>  ~~~~~~~~~~~~~~~~~~~~
>>
>> @@ -192,6 +196,8 @@ This is the default P-state selection algorithm if the
>>  :c:macro:`CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE` kernel configuration option
>>  is not set.
>>
>> +.. _Passive Mode:
>> +
>>  Passive Mode
>>  ------------
>>
>> @@ -432,6 +438,8 @@ the ``energy_model`` directory in ``debugfs`` (typlically mounted on
>>  User Space Interface in ``sysfs``
>>  =================================
>>
>> +.. _Global Attributes:
>> +
>>  Global Attributes
>>  -----------------
>>
>>
> 
> The diff LGTM, nevertheless.
> 
> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
> 
> Thanks.
> 



-- 
~Randy

Re: [PATCH] Documentation: pm: fix duplicate hyperlink target errors

[Rafael J. Wysocki]

On Wed, Oct 29, 2025 at 6:01 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>
>
>
> On 10/29/25 3:55 AM, Bagas Sanjaya wrote:
> > On Wed, Oct 29, 2025 at 01:47:37PM +0000, Swaraj Gaikwad wrote:
> >> Fix reST warnings in
> >> Documentation/admin-guide/pm/intel_pstate.rst caused by missing explicit
> >> hyperlink labels for section titles.
> >>
> >> Before this change, the following errors were printed during
> >> `make htmldocs`:
> >>
> >>   Documentation/admin-guide/pm/intel_pstate.rst:401:
> >>     ERROR: Indirect hyperlink target (id="id6") refers to target
> >>     "passive mode", which is a duplicate, and cannot be used as a
> >>     unique reference.
> >>   Documentation/admin-guide/pm/intel_pstate.rst:517:
> >>     ERROR: Indirect hyperlink target (id="id9") refers to target
> >>     "active mode", which is a duplicate, and cannot be used as a
> >>     unique reference.
> >>   Documentation/admin-guide/pm/intel_pstate.rst:611:
> >>     ERROR: Indirect hyperlink target (id="id15") refers to target
> >>     "global attributes", which is a duplicate, and cannot be used as
> >>     a unique reference.
> >>   ERROR: Duplicate target name, cannot be used as a unique reference:
> >>   "passive mode", "active mode", "global attributes".
> >
> > Hmm... I don't see these warnings when I build htmldocs by:
> >
> >   $ make SPHINXOPTS='-j 1' htmldocs
> >
> > My environment uses docutils 0.21.2 and Sphinx 8.2.3, though. What are yours?
>
>
> I do see the warnings and this patch fixes them in my testing.
>
> Acked-by: Randy Dunlap <rdunlap@infradead.org>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>
>
> docutils-3.13 (Docutils 0.22.2, Python 3.13.9, on linux)
> sphinx-build 8.2.3
>
> >> diff --git a/Documentation/admin-guide/pm/intel_pstate.rst b/Documentation/admin-guide/pm/intel_pstate.rst
> >> index 26e702c7016e..9cdd9dad6516 100644
> >> --- a/Documentation/admin-guide/pm/intel_pstate.rst
> >> +++ b/Documentation/admin-guide/pm/intel_pstate.rst
> >> @@ -62,6 +62,8 @@ a certain performance scaling algorithm.  Which of them will be in effect
> >>  depends on what kernel command line options are used and on the capabilities of
> >>  the processor.
> >>
> >> +.. _Active Mode:
> >> +
> >>  Active Mode
> >>  -----------
> >>
> >> @@ -94,6 +96,8 @@ Which of the P-state selection algorithms is used by default depends on the
> >>  Namely, if that option is set, the ``performance`` algorithm will be used by
> >>  default, and the other one will be used by default if it is not set.
> >>
> >> +.. _Active Mode With HWP:
> >> +
> >>  Active Mode With HWP
> >>  ~~~~~~~~~~~~~~~~~~~~
> >>
> >> @@ -192,6 +196,8 @@ This is the default P-state selection algorithm if the
> >>  :c:macro:`CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE` kernel configuration option
> >>  is not set.
> >>
> >> +.. _Passive Mode:
> >> +
> >>  Passive Mode
> >>  ------------
> >>
> >> @@ -432,6 +438,8 @@ the ``energy_model`` directory in ``debugfs`` (typlically mounted on
> >>  User Space Interface in ``sysfs``
> >>  =================================
> >>
> >> +.. _Global Attributes:
> >> +
> >>  Global Attributes
> >>  -----------------
> >>
> >>
> >
> > The diff LGTM, nevertheless.
> >
> > Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

Applied as 6.19 material, thanks!

Re: [PATCH] Documentation: pm: fix duplicate hyperlink target errors

[Swaraj Gaikwad]

Hi Bagas,

Thanks for reviewing!

Here are the versions from my environment where the warnings appear:

  sphinx-build 8.2.3
  Docutils 0.22.2, Python 3.13.7, on linux)

So it seems the issue shows up with docutils 0.22.2 but not with 0.21.2.

Thanks again for confirming the diff looks good!

Best regards,
Swaraj