Re: checkpatch doc suggestion

[Diederik de Haas <didi.debian@cknow.org>]

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

Hi Bagas,

On Friday, 3 May 2024 14:55:49 CEST Bagas Sanjaya wrote:
> On Tue, Apr 30, 2024 at 12:56:30PM +0200, Diederik de Haas wrote:
> > I think it would be really useful if (f.e.) the following URL
> > https://docs.kernel.org/dev-tools/checkpatch.html#BAD_FIXES_TAG
> > 
> > would lead me straight to the BAD_FIXES_TAG explanation.
> 
> So to add link to arbitrary location in the docs, you have to explicitly add
> target (anchor) to desired location. Then you can reference it using the
> target's name. For example, to accomplish your suggestion above:
> 
> ```
> diff --git a/Documentation/dev-tools/checkpatch.rst
> b/Documentation/dev-tools/checkpatch.rst index
> 12796899584739..002b0aa68b8022 100644
> --- a/Documentation/dev-tools/checkpatch.rst
> +++ b/Documentation/dev-tools/checkpatch.rst
> @@ -612,6 +612,8 @@ Commit message
> 
>      See:
> https://www.kernel.org/doc/html/latest/process/submitting-patches.html#desc
> ribe-your-changes
> 
> +.. _bad_fixes_tag:
> +
>    **BAD_FIXES_TAG**
>      The Fixes: tag is malformed or does not follow the community
> conventions. This can occur if the tag have been split into multiple lines
> ```

Thanks to your hint and some experimentation, I managed to add id attributes 
to the various ``dl`` elements and can directly reference the tags :-)

But I noticed 2 things in the generated HTML documentation:
1) The id attributes are all lowercase, regardless of how I defined them in 
``checkpatch.rst``
2) The underscores (``_``) have been replaced with dashes (``-``)

So instead of linking to checkpatch.html#BAD_FIXES_TAG I have to link to 
checkpatch.html#bad-fixes-tag. I was hoping that I could get the literal tags 
names (including underscores and uppercase letters) as id attribute.

Is something rst/sphinx always does or did I do something wrong?

Cheers,
  Diederik

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 228 bytes --]