lkml.org 
[lkml]   [2022]   [Jun]   [10]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [RFC PATCH 3/5] docs/doc-guide: Update guidelines for title adornments
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@linux.intel.com> 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

\
 
 \ /
  Last update: 2022-06-11 05:17    [W:0.114 / U:0.284 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site