Close #6698: doctest: Add :no-trim-doctest-flags: options

To control trimming doctest flags manually, this adds new options
:trim-doctest-flags: and :no-trim-doctest-flags: to doctest
directives.  It helps to describes doctest module itself in python
doc (see #6698).

1 files changed, 18 insertions, 3 deletions

diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst
index 33d6cf016..0fe9b535d 100644
--- a/doc/usage/extensions/doctest.rst
+++ b/doc/usage/extensions/doctest.rst
@@ -67,7 +67,7 @@ a comma-separated list of group names.
    default set of flags is specified by the :confval:`doctest_default_flags`
    configuration variable.
 
-   This directive supports three options:
+   This directive supports five options:
 
    * ``hide``, a flag option, hides the doctest block in other builders.  By
      default it is shown as a highlighted doctest block.
@@ -102,6 +102,11 @@ a comma-separated list of group names.
 
         Supported PEP-440 operands and notations
 
+   * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option,
+     doctest flags (comments looking like ``# doctest: FLAG, ...``) at the
+     ends of lines and ``<BLANKLINE>`` markers are removed (or not removed)
+     individually.  Default is ``trim-doctest-flags``.
+
    Note that like with standard doctests, you have to use ``<BLANKLINE>`` to
    signal a blank line in the expected output.  The ``<BLANKLINE>`` is removed
    when building presentation output (HTML, LaTeX etc.).
@@ -119,11 +124,16 @@ a comma-separated list of group names.
 
    A code block for a code-output-style test.
 
-   This directive supports one option:
+   This directive supports three options:
 
    * ``hide``, a flag option, hides the code block in other builders.  By
      default it is shown as a highlighted code block.
 
+   * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option,
+     doctest flags (comments looking like ``# doctest: FLAG, ...``) at the
+     ends of lines and ``<BLANKLINE>`` markers are removed (or not removed)
+     individually.  Default is ``trim-doctest-flags``.
+
    .. note::
 
       Code in a ``testcode`` block is always executed all at once, no matter how
@@ -149,7 +159,7 @@ a comma-separated list of group names.
    The corresponding output, or the exception message, for the last
    :rst:dir:`testcode` block.
 
-   This directive supports two options:
+   This directive supports four options:
 
    * ``hide``, a flag option, hides the output block in other builders.  By
      default it is shown as a literal block without highlighting.
@@ -157,6 +167,11 @@ a comma-separated list of group names.
    * ``options``, a string option, can be used to give doctest flags
      (comma-separated) just like in normal doctest blocks.
 
+   * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option,
+     doctest flags (comments looking like ``# doctest: FLAG, ...``) at the
+     ends of lines and ``<BLANKLINE>`` markers are removed (or not removed)
+     individually.  Default is ``trim-doctest-flags``.
+
    Example::
 
       .. testcode::