checkpatch doc suggestion

checkpatch doc suggestion

[Diederik de Haas]

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

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.

Cheers,
  Diederik

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

Re: checkpatch doc suggestion

[Bagas Sanjaya]

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

On Tue, Apr 30, 2024 at 12:56:30PM +0200, Diederik de Haas wrote:
> 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.

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#describe-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 (e.g., when
@@ -1254,3 +1256,4 @@ Others
 
   **TYPO_SPELLING**
     Some words may have been misspelled.  Consider reviewing them.
+    But have you :ref:`check this? <bad_fixes_tag>`

```

Thanks.

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

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

Re: checkpatch doc suggestion

[Diederik de Haas]

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

On Friday, 3 May 2024 14:55:49 CEST Bagas Sanjaya 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:

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

Cheers,
  Diederik

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

Re: checkpatch doc suggestion

[Bagas Sanjaya]

On 5/6/24 20:59, Diederik de Haas wrote:
> On Friday, 3 May 2024 14:55:49 CEST Bagas Sanjaya 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:
> 
> Thanks for that hint as I indeed didn't know how to add anchors in .rst files.
>
 
OK, thanks!

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

Re: checkpatch doc suggestion

[Diederik de Haas]

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

Re: checkpatch doc suggestion

[Akira Yokosawa]

Hi,

On Sun, 12 May 2024 17:58:10 +0200, Diederik de Haas wrote:
> 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?
> 

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

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

and "Hyperlink References" at:

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

, and other related sections therein.

HTH, Akira

> Cheers,
>   Diederik

Re: checkpatch doc suggestion

[Diederik de Haas]

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

On Monday, 13 May 2024 07:08:55 CEST Akira Yokosawa wrote:
> > 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?
> 
> 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.

https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization
taught me the reason why those conversions happened, so I'll use the
normalized version in my patch submission as well so that there's a 1-on-1
match between the source and the generated id attribute in the html docs.

> HTH, Akira

It sure did, thanks!

Cheers,
  Diederik

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