trac 30778: when a module is labeled "optional - xyz",

print a warning when doing introspection.

Documentation: recommend that people document it if they
add such a tag to a module.

Author: jhpalmieri

src/doc/en/developer/coding_basics.rst

@@ -1074,6 +1074,11 @@ framework. Here is a comprehensive list:
        This does not apply to files which are explicitly given
        as command line arguments: those are always tested.
 
+       If you add such a line to a file, you are strongly encouraged
+       to add a note to the module-level documentation, saying that
+       the doctests in this file will be skipped unless the
+       appropriate conditions are met.
+
   - **internet:** For lines that require an internet connection::
 
        sage: oeis(60843)                 # optional - internet

src/sage/doctest/control.py

@@ -216,6 +216,11 @@ def skipfile(filename, tested_optional_tags=False):
     - ``tested_optional_tags`` - a list or tuple or set of optional tags to test,
       or ``False`` (no optional test) or ``True`` (all optional tests)
 
+    If ``filename`` contains a line of the form ``"# sage.doctest:
+    optional - xyz")``, then this will return ``False`` if "xyz" is in
+    ``tested_optional_tags``. Otherwise, it returns the matching tag
+    ("optional - xyz").
+
     EXAMPLES::
 
         sage: from sage.doctest.control import skipfile
@@ -231,9 +236,11 @@ def skipfile(filename, tested_optional_tags=False):
         sage: with open(filename, "w") as f:
         ....:     _ = f.write("# sage.doctest: optional - xyz")
         sage: skipfile(filename, False)
+        'optional - xyz'
+        sage: bool(skipfile(filename, False))
         True
         sage: skipfile(filename, ['abc'])
-        True
+        'optional - xyz'
         sage: skipfile(filename, ['abc', 'xyz'])
         False
         sage: skipfile(filename, True)
@@ -252,11 +259,11 @@ def skipfile(filename, tested_optional_tags=False):
                 m = optionalfiledirective_regex.match(line)
                 if m:
                     if tested_optional_tags is False:
-                        return True
+                        return m.group(2)
                     optional_tags = parse_optional_tags('#' + m.group(2))
                     extra = optional_tags - set(tested_optional_tags)
                     if extra:
-                        return True
+                        return m.group(2)
             line_count += 1
             if line_count >= 10:
                 break

src/sage/misc/sageinspect.py

@@ -2031,6 +2031,15 @@ def sage_getdoc(obj, obj_name='', embedded_override=False):
         return ''
     r = sage_getdoc_original(obj)
     s = sage.misc.sagedoc.format(r, embedded=(embedded_override or EMBEDDED_MODE))
+    f = sage_getfile(obj)
+    if f:
+        from sage.doctest.control import skipfile
+        skip = skipfile(f)
+        if skip:
+            warn = """WARNING: the enclosing module is marked '{}',
+so doctests may not pass.""".format(skip)
+            s = warn + "\n\n" + s
+        pass
 
     # Fix object naming
     if obj_name != '':