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