mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Format options for doctest directives (#13107)
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
This commit is contained in:
Tim Hoffmann
GitHub
parent
2320c46b9e
commit
a2db696777
@ -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 <doctest-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:`skipping tests conditionally <doctest-skipif>`.
|
||||
|
||||
|
||||
.. 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
|
||||
|
||||
* ``hide``, a flag option, hides the doctest block in other builders. By
|
||||
default it is shown as a highlighted doctest block.
|
||||
.. rst:directive:option:: hide
|
||||
|
||||
* ``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.)
|
||||
Hide the doctest block in other builders.
|
||||
By default it is shown as a highlighted doctest block.
|
||||
|
||||
* ``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:: 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
|
||||
|
||||
>>> datetime.date.now() # doctest: +SKIP
|
||||
datetime.date(2008, 1, 1)
|
||||
|
||||
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`.
|
||||
|
||||
.. 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:
|
||||
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.
|
||||
* ``~=``: Compatible release clause
|
||||
* ``==``: Version matching clause
|
||||
* ``!=``: Version exclusion clause
|
||||
* ``<=``, ``>=``: Inclusive ordered comparison clause
|
||||
* ``<``, ``>``: Exclusive ordered comparison clause
|
||||
* ``===``: Arbitrary equality clause.
|
||||
|
||||
``pyversion`` option is followed :pep:`PEP-440: Version Specifiers
|
||||
<440#version-specifiers>`.
|
||||
``pyversion`` option is followed :pep:`PEP-440: Version Specifiers
|
||||
<440#version-specifiers>`.
|
||||
|
||||
.. versionadded:: 1.6
|
||||
.. versionadded:: 1.6
|
||||
|
||||
.. versionchanged:: 1.7
|
||||
.. versionchanged:: 1.7
|
||||
|
||||
Supported PEP-440 operands and notations
|
||||
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``.
|
||||
.. rst:directive:option:: trim-doctest-flags
|
||||
no-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.).
|
||||
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``.
|
||||
|
||||
Also, you can give inline doctest options, like in doctest::
|
||||
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.).
|
||||
|
||||
>>> datetime.date.now() # doctest: +SKIP
|
||||
datetime.date(2008, 1, 1)
|
||||
|
||||
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 <doctest-skipif>`.
|
||||
|
||||
.. rst:directive:: .. testcode:: [group]
|
||||
|
||||
A code block for a code-output-style test.
|
||||
|
||||
This directive supports three options:
|
||||
.. rubric:: Options
|
||||
|
||||
* ``hide``, a flag option, hides the code block in other builders. By
|
||||
default it is shown as a highlighted code block.
|
||||
.. rst:directive:option:: hide
|
||||
|
||||
* ``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``.
|
||||
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 ``<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:`skipping tests conditionally <doctest-skipif>`.
|
||||
|
||||
.. 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 ``<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
|
||||
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:`skipping tests conditionally <doctest-skipif>`.
|
||||
|
||||
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
|
||||
----------------------------
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user