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;
Message-ID: <42600ccb-8cfd-434e-cb4f-f871fd8de708@gmail.com>
Date:   Thu, 9 Jun 2022 22:27:27 +0900
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.9.1
Subject: [RFC PATCH 4/5] docs/doc-guide: Pull guidelines for title adornments
 out into subsection
Content-Language: en-US
To:     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>
References: <dccb5233-7f4f-1be6-d1f4-bbe9f42f88e0@gmail.com>
From:   Akira Yokosawa <akiyks@gmail.com>
In-Reply-To: <dccb5233-7f4f-1be6-d1f4-bbe9f42f88e0@gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

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

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 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