Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Format options for doctest directives #13107

Merged
merged 6 commits into from
Nov 13, 2024
Merged

Format options for doctest directives #13107

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
fc5f85c
Format doctest options in docs
timhoffm Nov 6, 2024
676ea3f
Apply suggestions from code review
timhoffm Nov 7, 2024
43de476
Merge branch 'master' into doc-doctest
timhoffm Nov 11, 2024
5db1ebc
Apply suggestions from code review
AA-Turner Nov 13, 2024
bf72d3e
doctest-skipif
AA-Turner Nov 13, 2024
de20c86
Merge branch 'master' into doc-doctest
AA-Turner Nov 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 106 additions & 51 deletions doc/usage/extensions/doctest.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]

Expand All @@ -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]

Expand All @@ -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 ``<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
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:`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

.. 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 ``<BLANKLINE>`` markers
individually. Default is ``trim-doctest-flags``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we have a :default: option to .. rst:directive:option::?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Theoretically yes. In practice, I believe it's not worth it. Without checking, I assume only a minor part of options have a real default value, instead they are often flags, or the default is some form of "emtpy"/not given e.g. in the case of :caption:, or the default is a behavior that needs a sentence of description, and does not have a simple value to list in a :default: option.
So, I'm fine with writing out "Default is ..." for the cases that make sense.


* ``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:`skipping tests conditionally <doctest-skipif>`.

.. note::

Expand All @@ -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::

Expand Down Expand Up @@ -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
----------------------------

Expand Down