conservative approach to fix #15184 (#16723)

doc/docgen.rst

@@ -76,6 +76,24 @@ Note that without the `*` following the name of the type, the documentation for
 this type would not be generated. Documentation will only be generated for
 *exported* types/procedures/etc.
 
+It's recommended to always add exactly **one** space after `##` for readability
+of comments — this extra space will be cropped from the parsed comments and
+won't influence RST formatting.
+
+.. note:: Generally, this baseline indentation level inside a documentation
+   comment may not be 1: it can be any since it is determined by the offset
+   of the first non-whitespace character in the comment.
+   After that indentation **must** be consistent on the following lines of
+   the same comment.
+   If you still need to add an additional indentation at the very beginning
+   (for RST block quote syntax) use backslash \\ before it:
+
+   .. code-block:: nim
+      ## \
+      ##
+      ##    Block quote at the first line.
+      ##
+      ## Paragraph.
 
 Nim file input
 -----------------

doc/manual.rst

@@ -247,7 +247,7 @@ Multiline documentation comments also exist and support nesting too:
 .. code-block:: nim
   proc foo =
     ##[Long documentation comment
-    here.
+       here.
     ]##