Better indentation examples (#1858)

Author: NickVolynkin

doc/contributing/docs/_includes/indentation.rst

@@ -1,10 +1,16 @@
-#.  list item 1
-#.  list item 2
+|...|...|...|...
+#.  List item 1.
+    Paragraph continues.
 
-    *   nested list item
+    Second paragraph.
+
+#.  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,27 @@ 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.
 
+Note that you have to use two or three spaces instead of one.
+It is allowed in rST markup:
+
+..  code-block:: rst
+
+    |...|...|...|...
+    *   unordered list
+    #.  ordered list
+    ..  directive::
+    |...|...|...|...
+
 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