checkpatch doc suggestion

Hi,

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.

Quoted 4 lines

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:

Quoted 3 lines · On Friday, 3 May 2024 14:55:49 CEST Bagas Sanjaya wrote:

Quoted 3 lines

I think it would be really useful if (f.e.) the following URL
https://docs.kernel.org/dev-tools/checkpatch.html#BAD_FIXES_TAG

Quoted 5 lines

Quoted 1 line

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:

Thanks for that hint as I indeed didn't know how to add anchors in .rst files.

Quoted 4 lines · Diederik de Haas

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:

```

(quoted diff) +0 -0

b/Documentation/dev-tools/checkpatch.rst index
12796899584739..002b0aa68b8022 100644

Documentation/dev-tools/checkpatch.rst +0 -0

@@ -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 ```

Hi Bagas,

Quoted 22 lines · On Friday, 3 May 2024 14:55:49 CEST Bagas Sanjaya wrote:

Quoted 4 lines · Diederik de Haas

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:

```

(quoted diff) +0 -0

b/Documentation/dev-tools/checkpatch.rst index
12796899584739..002b0aa68b8022 100644

Documentation/dev-tools/checkpatch.rst +0 -0

@@ -612,6 +612,8 @@ Commit message
 
     See:

https://www.kernel.org/doc/html/latest/process/submitting-patches.html#desc
ribe-your-changes

Quoted 6 lines

+.. _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

Quoted 9 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 (``-``)

Quoted 5 lines

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?

For authoritative info, I'd suggest consulting the reST reference for "Hyperlink Targets" at:

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlin
k-targets

and "Hyperlink References" at:

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlin
k-references

, and other related sections therein.

HTH, Akira