docstring wide optional markup

[nthiery]

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

[nthiery]

Branch: u/nthiery/docstring_wide_optional_markup

[saraedum]

comment:2

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

[saraedum]

Commit: ae1d9e4

[jdemeyer]

comment:3

See also #3260.

[jdemeyer]

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.

[mkoeppe]

comment:6

For a module-level directive in the same direction, see #30778