From ee3f3619929d1dc9277c6081003cf58268029345 Mon Sep 17 00:00:00 2001
From: Latosha Maltba <79100569+latosha-maltba@users.noreply.github.com>
Date: Mon, 27 Sep 2021 09:06:52 +0000
Subject: [PATCH] Document indent behaviour for directives

Mention how the indent of the contents for directives is chosen and what
the effect on directives which are sensitive to whitespace is,
e.g. code-block.
---
 doc/usage/restructuredtext/basics.rst | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst
index d96b1fe3867..16cfc6109f7 100644
--- a/doc/usage/restructuredtext/basics.rst
+++ b/doc/usage/restructuredtext/basics.rst
@@ -410,7 +410,27 @@ following the arguments and indicated by the colons).  Options must be indented
 to the same level as the directive content.
 
 The directive content follows after a blank line and is indented relative to
-the directive start.
+the directive start or if options are present, by the same amount as the
+options.
+
+Be careful as the indent is not a fixed number of whitespace, e.g. three, but
+any number whitespace.  This can be surprising when a fixed indent is used
+throughout the document and can make a difference for directives which are
+sensitive to whitespace. Compare::
+
+   .. code-block::
+      :caption: A cool example
+
+          The output of this line starts with four spaces.
+
+   .. code-block::
+
+          The output of this line has no spaces at the beginning.
+
+In the first code block, the indent for the content was fixated by the option
+line to three spaces, consequently the content starts with four spaces.
+In the latter the indent was fixed by the content itself to seven spaces, thus
+it does not start with a space.
 
 
 Images