diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst index f257509de22..3b41b9da812 100644 --- a/doc/usage/extensions/doctest.rst +++ b/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:`skipping tests conditionally `. + .. 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:`skipping tests conditionally `. + .. rst:directive:: .. doctest:: [group] @@ -67,72 +83,99 @@ 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: + + .. code-block:: pycon - * ``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 ```` 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 ```` to - signal a blank line in the expected output. The ```` is removed - when building presentation output (HTML, LaTeX etc.). + .. rst:directive:option:: trim-doctest-flags + 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 ```` 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 ```` to + signal a blank line in the expected output. The ```` 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:`skipping tests conditionally `. .. 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 + no-trim-doctest-flags + + Whether to trim remove doctest flags (comments looking like + ``# doctest: FLAG, ...``) at the ends of lines and ```` 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 ```` markers are removed (or not removed) - individually. Default is ``trim-doctest-flags``. + Skip the directive if the python expression *condition* is True. + See :ref:`skipping tests conditionally `. .. note:: @@ -159,18 +202,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 ```` 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 + no-trim-doctest-flags + + Whether to trim remove doctest flags (comments looking like + ``# doctest: FLAG, ...``) at the ends of lines and ```` 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:`skipping tests conditionally `. Example:: @@ -217,6 +270,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! +.. _doctest-skipif: + Skipping tests conditionally ----------------------------