Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Jani Nikula <jani.nikula@linux.intel.com>
To:     Akira Yokosawa <akiyks@gmail.com>,
        Jonathan Corbet <corbet@lwn.net>, linux-doc@vger.kernel.org
Cc:     Mauro Carvalho Chehab <mchehab@kernel.org>,
        "Maciej W. Rozycki" <macro@orcam.me.uk>,
        Miguel Ojeda <ojeda@kernel.org>, linux-kernel@vger.kernel.org,
        Akira Yokosawa <akiyks@gmail.com>
Subject: Re: [RFC PATCH 3/5] docs/doc-guide: Update guidelines for title
 adornments
In-Reply-To: <732154bc-aa35-2326-2b64-87b6c4dd02e7@gmail.com>
Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo
References: <dccb5233-7f4f-1be6-d1f4-bbe9f42f88e0@gmail.com>
 <732154bc-aa35-2326-2b64-87b6c4dd02e7@gmail.com>
Date:   Fri, 10 Jun 2022 12:11:15 +0300
Message-ID: <871qvw2898.fsf@intel.com>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

On Thu, 09 Jun 2022, Akira Yokosawa <akiyks@gmail.com> wrote:
> Existing guidelines predate the sub-directory wise document
> management.
>
> Update the guidelines to reflect the current state of affairs.
>
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Cc: Miguel Ojeda <ojeda@kernel.org>
> ---
>  Documentation/doc-guide/sphinx.rst | 66 +++++++++++++++++++++++-------
>  1 file changed, 52 insertions(+), 14 deletions(-)
>
> diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
> index efcccab68286..f257c4785607 100644
> --- a/Documentation/doc-guide/sphinx.rst
> +++ b/Documentation/doc-guide/sphinx.rst
> @@ -202,34 +202,72 @@ Here are some specific guidelines for the kernel documentation:
>  * Also update the content, not just the formatting, when converting
>    documentation.
>  
> -* Please stick to this order of heading adornments:
> +* Please stick to this relative order of section title adornments:
>  
> -  1. ``=`` with overline for document title::
> +  1. ``=`` with overline for 1st level titles::
>  
> -       ==============
> -       Document title
> -       ==============
> +       ===============
> +       1st level title
> +       ===============
>  
> -  2. ``=`` for chapters::
> +  2. ``=`` for 2nd level titles::
>  
> -       Chapters
> -       ========
> +       2nd level title
> +       ===============
>  
> -  3. ``-`` for sections::
> +  3. ``-`` for 3rd level titles::
>  
> -       Section
> -       -------
> +       3rd level title
> +       ---------------
>  
> -  4. ``~`` for subsections::
> +  4. ``~`` for 4th level titles::
>  
> -       Subsection
> -       ~~~~~~~~~~
> +       4th level title
> +       ~~~~~~~~~~~~~~~
>  
>    Although RST doesn't mandate a specific order ("Rather than imposing a fixed
>    number and order of section title adornment styles, the order enforced will be
>    the order as encountered."), having the higher levels the same overall makes
>    it easier to follow the documents.
>  
> +  .. note::
> +    - It is not easy to tell the levels (chapter, section, etc.) of title
> +      adornments in a particular .rst file.  A title that appears first in
> +      a .rst file can be at any level of document, chapter, section, or
> +      subsection (or deeper) depending on the file's inclusion depth.
> +
> +    - The RST language does not have an explicit means to specify a "document
> +      title".  Quote from the RST documentation\ [#rstdoc]_ with minor edit:
> +
> +	*Specifically, there is no way to indicate a document title and
> +	subtitle explicitly in reStructuredText.  Instead, a lone top-level
> +	section title can be treated as the document title.*
> +
> +      In the kernel documentation processing, the first title in a top-level
> +      ``index.rst`` can be considered the document title.  In HTML, as each
> +      .html output has its source .rst file, the title which happens to come
> +      first is used as the title of the resulting HTML page.
> +      Alternatively, it is possible to specify a page title by using the
> +      directive "title".\ [#rstdirtitle]_
> +
> +    - There may be a 2nd or 3rd level adornment at the first title in a .rst
> +      file.  This usage is often seen in .rst files that are derived and
> +      split from a larger .rst file.  It is sufficient if relative order is
> +      preserved.
> +
> +    .. [#rstdoc] https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#document
> +    .. [#rstdirtitle] https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata-document-title
> +
> +  .. warning::
> +    For existing documents, manually updating title adornments just to meet
> +    these guidelines is not recommended.  Such changes can be error-prone and
> +    may break section hierarchy without being caught by reviewers.  They may
> +    be justified if done in conjunction with a section reorganization or
> +    similar.
> +
> +    It would be appreciated if adjustment of those adornments could be
> +    automated in some way.
> +

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.)

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.


BR,
Jani.


>  * For inserting fixed width text blocks (for code examples, use case
>    examples, etc.), use ``::`` for anything that doesn't really benefit
>    from syntax highlighting, especially short snippets. Use

-- 
Jani Nikula, Intel Open Source Graphics Center