Re: [PATCH v2] Documentation: add initial iomap kdoc

[Randy Dunlap <rdunlap@infradead.org>]

On 5/22/23 18:20, Darrick J. Wong wrote:
> On Thu, May 18, 2023 at 10:04:43PM -0700, Christoph Hellwig wrote:
>> On Thu, May 18, 2023 at 08:01:05AM -0700, Luis Chamberlain wrote:
>>> +        Mapping of heading styles within this document:
>>> +        Heading 1 uses "====" above and below
>>> +        Heading 2 uses "===="
>>> +        Heading 3 uses "----"
>>> +        Heading 4 uses "````"
>>> +        Heading 5 uses "^^^^"
>>> +        Heading 6 uses "~~~~"
>>> +        Heading 7 uses "...."
>>> +
>>> +        Sections are manually numbered because apparently that's what everyone
>>
>> Why are you picking different defaults then the rest of the kernel
>> documentation?
> 
> I bet Luis copied that from the online fsck document.
> 
> IIRC the doc generator is smart enough to handle per-file heading usage.
> The rst parser sourcecode doesn't seem to have harcoded defaults; every
> time it sees an unfamiliar heading style in a .rst file, it adds that as
> the next level down in the hierarchy.
> 
> Also, where are the "proper" headings documented for Documentation/?

Documentation/doc-guide/sphinx.rst:

* Please stick to this order of heading adornments:

and following lines.

-- 
~Randy