Feature: skip doctests conditionally

[akaihola]

Subject: A :skipif: option for doctest directives

Feature or Bugfix

• Feature

Purpose

• Unit tests can be skipped conditionally using the @unittest.skipIf() decorator. A similar feature would be useful for doctests when run by Sphinx.

Detail

Example use cases:

• different tests for specific versions of dependencies
• skip tests in absence of optional dependencies
• skip tests in absence of a network or VPN
• skip tests in absence of some hardware

Relates

• Feature request: Skip doctest conditionally #5273
• The feature was also mentioned on Stack Overflow in the Sphinx doctest: conditional test skipping question.

[codecov]

Codecov Report

Merging #5307 into master will increase coverage by 0.02%.
The diff coverage is 82.6%.

@@            Coverage Diff             @@
##           master    #5307      +/-   ##
==========================================
+ Coverage   82.21%   82.24%   +0.02%     
==========================================
  Files         296      296              
  Lines       39346    39367      +21     
  Branches     6058     6063       +5     
==========================================
+ Hits        32348    32376      +28     
+ Misses       5669     5663       -6     
+ Partials     1329     1328       -1

Impacted Files	Coverage Δ
tests/test_ext_doctest.py	92.72% <81.81%> (-2.73%)	⬇️
sphinx/ext/doctest.py	83.87% <83.33%> (+3.2%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update bce956d...098f37f. Read the comment docs.

[tk0miya]

Perfect! LGTM!

[tk0miya]

Merged.
Thank you for great contribution!

[akaihola]

Thank you @tk0miya, I'm really happy to get this feature in. And the experience of contributing to Sphinx was one of the best I've had with any Open Source project. Great work guys!

[timokau]

Is it somehow possible to add the :skipif: option to doctest blocks (i.e. without explicit .. doctest:: directive)?

Example:

>>> print(42)
42

How can I skip this test conditionally? The only option I found is adding .. doctest::, but that makes it necessary to change indentation as it apparently has to have one indentation level less than the doctest block.

[akaihola]

@timokau, hi, I'm not 100% sure, but I would guess that it's not possible to apply :skipif: to such doctest blocks.

Note that the code in a .. doctest:: block can be indented by three or more spaces. So a four-space indent works just as well!

[timokau]

Okay, thanks for the reply. I'll just live with the indentation "issue" then. For what its worth, this illustrates the issue I'm talking about:

The indentation issue is:

def fn():
"""
This does something.

Examples:

	Here it prints something:

.. doctest::
   :skipif: True

	>>> fn()
	"something"

"""

[wojdyr]

Thanks for this feature!

I just realized that :skipif: is evaluated also when building documentation (make html) not just during make doctest. So if a certain module is missing on ReadTheDocs then corresponding doctest blocks are not included in documentation. This is easy to workaround, but I wonder if it's intentional?

[akaihola]

@wojdyr, that's a really good point. Skipping on make html was not intentional. I remember it kind of occurring to me at some point, but apparently I forgot about it. Feel free to create another issue about this, it would very much make sense to fix it.

[wojdyr]

@akaihola I've opened #6068 .
Thanks again for :skipif:, it solved the problem I had with doctest blocks.