Format doctest options in docs

Author: timhoffm

doc/usage/extensions/doctest.rst

@@ -51,6 +51,14 @@ a comma-separated list of group names.
    A setup code block.  This code is not shown in the output for other builders,
    but executed before the doctests of the group(s) it belongs to.
 
+   .. rubric:: Options
+
+   .. rst:directive:option:: skipif: condition
+      :type: text
+
+      Skip the directive if the python expression *condition* is True.
+      See :ref:`skipif`.
+
 
 .. rst:directive:: .. testcleanup:: [group]
 
@@ -59,6 +67,14 @@ a comma-separated list of group names.
 
    .. versionadded:: 1.1
 
+   .. rubric:: Options
+
+   .. rst:directive:option:: skipif: condition
+      :type: text
+
+      Skip the directive if the python expression *condition* is True.
+      See :ref:`skipif`.
+
 
 .. rst:directive:: .. doctest:: [group]
 
@@ -67,72 +83,97 @@ a comma-separated list of group names.
    default set of flags is specified by the :confval:`doctest_default_flags`
    configuration variable.
 
-   This directive supports five options:
+   .. rubric:: Options
+
+   .. rst:directive:option:: hide
+
+     Hide the doctest block in other builders.  By default it is shown as a
+     highlighted doctest block.
+
+   .. rst:directive:option:: options: doctest flags
+      :type: comma separated list
+
+      A comma-separated list of doctest flags that apply to each example in the
+      tests.  (You still can give explicit flags per example, with doctest comments,
+      but they will show up in other builders too.)
+
+      Alternatively, you can give inline doctest options, like in doctest::
 
-   * ``hide``, a flag option, hides the doctest block in other builders.  By
-     default it is shown as a highlighted doctest block.
+         >>> datetime.date.now()   # doctest: +SKIP
+         datetime.date(2008, 1, 1)
 
-   * ``options``, a string option, can be used to give a comma-separated list of
-     doctest flags that apply to each example in the tests.  (You still can give
-     explicit flags per example, with doctest comments, but they will show up in
-     other builders too.)
+      They will be respected when the test is run, but by default will be stripped from
+      presentation output. You can prevent stripping using the option
+      :rst:dir:`doctest:no-trim-doctest-flags`.
 
-   * ``pyversion``, a string option, can be used to specify the required Python
-     version for the example to be tested. For instance, in the following case
-     the example will be tested only for Python versions greater than 3.12::
+   .. rst:directive:option:: pyversion
+      :type: text
+
+      Specify the required Python version for the example to be tested. For instance,
+      in the following case the example will be tested only for Python versions greater
+      than 3.12::
 
          .. doctest::
             :pyversion: > 3.12
 
-     The following operands are supported:
-
-     * ``~=``: Compatible release clause
-     * ``==``: Version matching clause
-     * ``!=``: Version exclusion clause
-     * ``<=``, ``>=``: Inclusive ordered comparison clause
-     * ``<``, ``>``: Exclusive ordered comparison clause
-     * ``===``: Arbitrary equality clause.
+      The following operands are supported:
 
-     ``pyversion`` option is followed :pep:`PEP-440: Version Specifiers
-     <440#version-specifiers>`.
+      * ``~=``: Compatible release clause
+      * ``==``: Version matching clause
+      * ``!=``: Version exclusion clause
+      * ``<=``, ``>=``: Inclusive ordered comparison clause
+      * ``<``, ``>``: Exclusive ordered comparison clause
+      * ``===``: Arbitrary equality clause.
 
-     .. versionadded:: 1.6
+      ``pyversion`` option is followed :pep:`PEP-440: Version Specifiers
+      <440#version-specifiers>`.
 
-     .. versionchanged:: 1.7
+      .. versionadded:: 1.6
 
-        Supported PEP-440 operands and notations
+      .. versionchanged:: 1.7
 
-   * ``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``.
+         Supported PEP-440 operands and notations
 
-   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.).
+   .. rst:directive:option:: trim-doctest-flags
+   .. rst:directive:option:: no-trim-doctest-flags
 
-   Also, you can give inline doctest options, like in doctest::
+      Whether to trim remove doctest flags (comments looking like
+      ``# doctest: FLAG, ...``) at the ends of lines and ``<BLANKLINE>`` markers
+      individually.  Default is ``trim-doctest-flags``.
 
-      >>> datetime.date.now()   # doctest: +SKIP
-      datetime.date(2008, 1, 1)
+      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.).
 
-   They will be respected when the test is run, but stripped from presentation
-   output.
+   .. rst:directive:option:: skipif: condition
+      :type: text
 
+      Skip the directive if the python expression *condition* is True.
+      See :ref:`skipif`.
 
 .. rst:directive:: .. testcode:: [group]
 
    A code block for a code-output-style test.
 
-   This directive supports three options:
+   .. rubric:: Options
+
+   .. rst:directive:option:: hide
+
+      Hide the code block in other builders.  By default it is shown as a
+      highlighted code block.
+
+   .. rst:directive:option:: trim-doctest-flags
+   .. rst:directive:option:: no-trim-doctest-flags
+
+      Whether to trim remove doctest flags (comments looking like
+      ``# doctest: FLAG, ...``) at the ends of lines and ``<BLANKLINE>`` markers
+      individually.  Default is ``trim-doctest-flags``.
 
-   * ``hide``, a flag option, hides the code block in other builders.  By
-     default it is shown as a highlighted code block.
+   .. rst:directive:option:: skipif: condition
+      :type: text
 
-   * ``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``.
+      Skip the directive if the python expression *condition* is True.
+      See :ref:`skipif`.
 
    .. note::
 
@@ -159,18 +200,28 @@ a comma-separated list of group names.
    The corresponding output, or the exception message, for the last
    :rst:dir:`testcode` block.
 
-   This directive supports four options:
+   .. rst:directive:option:: hide
 
-   * ``hide``, a flag option, hides the output block in other builders.  By
-     default it is shown as a literal block without highlighting.
+     Hide the doctest block in other builders.  By default it is shown as a
+     highlighted doctest block.
 
-   * ``options``, a string option, can be used to give doctest flags
-     (comma-separated) just like in normal doctest blocks.
+   .. rst:directive:option:: options: doctest flags
+      :type: comma separated list
 
-   * ``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``.
+      A comma-separated list of doctest flags.
+
+   .. rst:directive:option:: trim-doctest-flags
+   .. rst:directive:option:: no-trim-doctest-flags
+
+      Whether to trim remove doctest flags (comments looking like
+      ``# doctest: FLAG, ...``) at the ends of lines and ``<BLANKLINE>`` markers
+      individually.  Default is ``trim-doctest-flags``.
+
+   .. rst:directive:option:: skipif: condition
+      :type: text
+
+      Skip the directive if the python expression *condition* is True.
+      See :ref:`skipif`.
 
    Example::
 
@@ -217,6 +268,8 @@ The following is an example for the usage of the directives.  The test via
       This parrot wouldn't voom if you put 3000 volts through it!
 
 
+.. _skipif:
+
 Skipping tests conditionally
 ----------------------------