Better indentation examples

Author: NickVolynkin

doc/contributing/docs/_includes/indentation.rst

@@ -1,10 +1,15 @@
-#.  list item 1
-#.  list item 2
+|...|...|...|...
+#.  List item 1.
 
-    *   nested list item
+    Second paragraph in the list item.
+
+#.  List item 2.
+
+    *   Nested list item.
 
         ..  code-block:: bash
 
-            # this is a code block inside a nested list item
+            # this code block is in a nested list item
 
-    *   another nested list item
+    *   Another nested list item.
+|...|...|...|...

doc/contributing/docs/markup.rst

@@ -67,14 +67,30 @@ It's best if all indents are multiples of 4 spaces, even in lists. Otherwise
 the document is not consistent. Also, it is much easier to put indents
 with tabs than manually.
 
+To make 4-space indents, add two or three spaces instead of one.
+It is allowed in rST markup.
+
+..  code-block:: rst
+
+    |...|...|...|...
+    ..  directive::
+        ..  nested-directive::
+    1.  numbered list
+    #.  autonumbered list
+    *   bullet list
+        *   next level list
+    |...|...|...|...
+
 Example:
 
 ..  literalinclude:: _includes/indentation.rst
     :language: rst
 
 Resulting output:
 
-..  include:: _includes/indentation.rst
+    ..  include:: _includes/indentation.rst
+        :start-line: 1
+        :end-line: -1
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Code snippets