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
