sage.doctest.control, sage.features.sagemath: Provide/use optional tags

src/sage/doctest/control.py

@@ -53,6 +53,9 @@
 except ImportError:
     pass
 
+from sage.features.sagemath import sage_optional_tags
+auto_optional_tags |= sage_optional_tags()
+
 class DocTestDefaults(SageObject):
     """
     This class is used for doctesting the Sage doctest module.

src/sage/features/sagemath.py

@@ -7,6 +7,9 @@
 class sage__combinat(PythonModule):
 
     def __init__(self):
+        # sage.combinat will be a namespace package.
+        # Testing whether sage.combinat itself can be imported is meaningless.
+        # Hence, we test a Python module within the package.
         PythonModule.__init__('sage.combinat.combinations')
 
 
@@ -26,3 +29,28 @@ class sage__symbolic(PythonModule):
 
     def __init__(self):
         PythonModule.__init__('sage.symbolic.expression', spkg="sagemath_symbolics")
+
+
+def sage_optional_tags():
+    """
+    Return tags for conditionalizing doctests.
+
+    These tags are named after Python packages/modules (e.g., :mod:`~sage.symbolic`),
+    not distribution packages (``sagemath-symbolics``).
+
+    This is motivated by a separation of concerns: The author of a module that depends
+    on some functionality provided by a Python module usually already knows the
+    name of the Python module, so we do not want to force the author to also
+    know about the distribution package that provides the Python module.
+
+    Instead, we associate distribution packages to Python modules in
+    :mod:`sage.features.sagemath` via the ``spkg`` parameter of :class:`PythonModule``.
+    """
+    if sage__combinat().is_functional():
+        yield 'sage.combinat'
+    if sage__graphs().is_functional():
+        yield 'sage.graphs'
+    if sage__rings__real_double().is_functional():
+        yield 'sage.rings.real_double'
+    if sage__symbolic().is_functional():
+        yield 'sage.symbolic'