summaryrefslogtreecommitdiff
path: root/Documentation/doc-guide/sphinx.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/doc-guide/sphinx.rst')
-rw-r--r--Documentation/doc-guide/sphinx.rst17
1 files changed, 16 insertions, 1 deletions
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 96fe7ccb2c67..532d65b70500 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -73,7 +73,16 @@ Specific guidelines for the kernel documentation
Here are some specific guidelines for the kernel documentation:
-* Please don't go overboard with reStructuredText markup. Keep it simple.
+* Please don't go overboard with reStructuredText markup. Keep it
+ simple. For the most part the documentation should be plain text with
+ just enough consistency in formatting that it can be converted to
+ other formats.
+
+* Please keep the formatting changes minimal when converting existing
+ documentation to reStructuredText.
+
+* Also update the content, not just the formatting, when converting
+ documentation.
* Please stick to this order of heading adornments:
@@ -103,6 +112,12 @@ Here are some specific guidelines for the kernel documentation:
the order as encountered."), having the higher levels the same overall makes
it easier to follow the documents.
+* 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.
+
the C domain
------------