On Fri, 10 Jun 2022 18:08:43 +0200,
Miguel Ojeda wrote:
> On Fri, Jun 10, 2022 at 11:11 AM Jani Nikula
> <jani.nikula@xxxxxxxxxxxxxxx> wrote:
Thank Jani and Miguel for chiming in!
As this is a RFC patch, I'm glad to have nice comments from both of you.
>>
>> When I wrote the original guidelines, it was my subjective decision to
>> steer towards using the same title adornment styles and ordering across
>> the kernel documentation. I intentionally left out all the
>> reStructuredText details about this, because the definitive
>> documentation is the reStructuredText documentation we can refer to.
>>
>> While the "Nth level title" is a more precise description, I'm not sure
>> it's actually helpful without describing how these levels should map to
>> kernel documentation structure. (Not saying the original did that
>> either, but then there wasn't much structure to speak of.)
I agree that we need to cover in doc-guide the way the kernel documentation
is organized and managed. Total lack of such documentation is kind of
surprising to me.
>
> To give a bit of context: this patch followed from a question I asked
> to Jonathan and Akira privately. Currently it is hard to tell the
> "nesting level", and even worse, existing files are not consistent and
> checking is not automated. Therefore, an easy way to handle this is to
> request to follow the same pattern regardless of nesting across the
> tree.
>
>> Improving the documentation on documentation is great, but I think it's
>> a bad sign when length of the notes and warnings on something far exceed
>> the length of the thing being documented. The bulk of the text should be
>> helpful enough for people to DTRT, while leaving out exhaustive
>> descriptions of all the details that should just be references to
>> reStructuredText documentation.
So, I was not aware of such a hidden rule on what should _not_ be in
doc-guide. :-)
In my opinion, RST documentation is not easy to follow especially for
new contributors, and putting some useful tips somewhere in doc-guide
would improve situation.
I agree with you that those notes and warning don't belong to guidelines.
Maybe add a section collecting RST tips and tricks mainly consisting
of pointers to RST and docutils documentation.
>
> Perhaps we can move the rationale to the commit message, and keep only
> the current rules in the document. What about something like:
>
> """
> Please stick to this relative order of adornments within each file
> (i.e. regardless of nesting level across the kernel tree):
>
> 1. ``=`` with overline.
> 2. ``=``.
> 3. ``-``.
> 4. ``~``.
>
> For instance::
>
> =====
> First
> =====
>
> Second
> ======
>
> Third
> -----
>
> Fourth
> ~~~~~~
> """
I'm more inclined to keep "level"s in the example.
Without them, a new contributor might be confused to use those
adornments exactly in that order, for example:
==============
Document title
==============
Chapter A
=========
Section A.1
-----------
Section A.2
~~~~~~~~~~~
Section A.3
???????????
Unlikely, but possible...
Anyway, I'll post a v2 for your further comments.
Might take a while.
Thanks, Akira
>
> Cheers,
> Miguel
