[RFC PATCH 4/5] docs/doc-guide: Pull guidelines for title adornments out into subsection

[Akira Yokosawa]

As it becomes too large as an item in bullet lists, make it a
subsection of its own.

Signed-off-by: Akira Yokosawa <akiyks@xxxxxxxxx>
---
 Documentation/doc-guide/sphinx.rst | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index f257c4785607..f8bbf86fa15a 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -202,7 +202,16 @@ Here are some specific guidelines for the kernel documentation:
 * Also update the content, not just the formatting, when converting
   documentation.
 
-* Please stick to this relative order of section title adornments:
+* 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
+  ``.. code-block:: <language>`` for longer code blocks that benefit
+  from highlighting. For a short snippet of code embedded in the text, use \`\`.
+
+Guidelines for title adornments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Please stick to this relative order of section title adornments:
 
   1. ``=`` with overline for 1st level titles::
 
@@ -225,12 +234,12 @@ Here are some specific guidelines for the kernel documentation:
        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.
+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::
+.. 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
@@ -258,7 +267,7 @@ Here are some specific guidelines for the kernel documentation:
     .. [#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::
+.. 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
@@ -268,12 +277,6 @@ Here are some specific guidelines for the kernel documentation:
     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
-  ``.. code-block:: <language>`` for longer code blocks that benefit
-  from highlighting. For a short snippet of code embedded in the text, use \`\`.
-
 
 the C domain
 ------------
-- 
2.25.1