docstring wide optional markup
nthiery opened this issue · 6 comments
It's quite common that optional tests come in batch, typically when documenting a method that is only available when a certain feature or package is available. Having to mark each and every test with # optional xxx is redundant and reduces readability.
This ticket implements a Sphinx style markup to disable all doctests following it::
"""
...
EXAMPLES::
sage: ...
.. OPTIONAL:: gap3
::
sage: gap3(...)
sage: gap3(...)
"""
TODO:
- Is this the right markup? I would prefer ".. REQUIRE:: gap3" but this is not super consistent with the line-by-line markup.
- It could be desirable to have a markup to disable all tests in the module; possibly by using the above markup in the module docstring.
CC: @mmasdeu
Component: doctest framework
Author: Nicolas M. Thiéry
Branch/Commit: u/nthiery/docstring_wide_optional_markup @ ae1d9e4
Issue created by migration from https://trac.sagemath.org/ticket/20427
Let me know when you need a reviewer (in case sage-devel approves of this in the end.)
New commits:
ae1d9e4 | 20427: preliminary implementation of the .. OPTIONAL:: markup |
Replying to @nthiery:
Having to mark each and every test with # optional xxx is redundant and reduces readability.
One the other hand, it's not always needed to mark every test # optional. In many cases, a module depending on an optional package still has some stuff which does not need the package and which could be tested unconditionally. Typically you have some high-level object modelling something and creating/displaying/modifying that object does not require the optional package. The package is only needed when doing something mathematically interesting.
The above paragraph certainly does not apply to all optional packages, but we should we careful that people don't become lazy and mark a whole file # optional when many doctests in that file are not optional.