[RFC PATCH 3/5] docs/doc-guide: Update guidelines for title adornments

[Akira Yokosawa <akiyks@gmail.com>]

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.
+
 * 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
-- 
2.25.1