Trac #33085: adjust dochtml label so doctests pass when html doc is n…

…ot built/installed

This includes
 - #33064: do not fail when docbuild cache cannot be saved
 - remove dochtml label from some tests that don't need docs installed
 - add dochtml label to some tests that need docs installed
 - use dochtml as default option only when html docs are installed

URL: https://trac.sagemath.org/33085
Reported by: tornaria
Ticket author(s): Gonzalo Tornaría
Reviewer(s): Matthias Koeppe

src/sage/docs/conf.py

@@ -719,8 +719,8 @@ def call_intersphinx(app, env, node, contnode):
     Check that the link from the thematic tutorials to the reference
     manual is relative, see :trac:`20118`::
 
-        sage: from sage.env import SAGE_DOC  # optional - sagemath_doc_html
-        sage: thematic_index = os.path.join(SAGE_DOC, "html", "en", "thematic_tutorials", "index.html")  # optional - sagemath_doc_html
+        sage: from sage.env import SAGE_DOC
+        sage: thematic_index = os.path.join(SAGE_DOC, "html", "en", "thematic_tutorials", "index.html")
         sage: for line in open(thematic_index).readlines():  # optional - sagemath_doc_html
         ....:     if "padics" in line:
         ....:         _ = sys.stdout.write(line)

src/sage/misc/sagedoc.py

@@ -18,8 +18,8 @@
 Check that argspecs of extension function/methods appear correctly,
 see :trac:`12849`::
 
-    sage: from sage.env import SAGE_DOC  # optional - sagemath_doc_html
-    sage: docfilename = os.path.join(SAGE_DOC, 'html', 'en', 'reference', 'calculus', 'sage', 'symbolic', 'expression.html')  # optional - sagemath_doc_html
+    sage: from sage.env import SAGE_DOC
+    sage: docfilename = os.path.join(SAGE_DOC, 'html', 'en', 'reference', 'calculus', 'sage', 'symbolic', 'expression.html')
     sage: with open(docfilename) as fobj:  # optional - sagemath_doc_html
     ....:     for line in fobj:
     ....:         if "#sage.symbolic.expression.Expression.numerical_approx" in line:
@@ -845,12 +845,12 @@ def _search_src_or_doc(what, string, extra1='', extra2='', extra3='',
 
     ::
 
-        sage: from sage.misc.sagedoc import _search_src_or_doc  # optional - sagemath_doc_html
-        sage: len(_search_src_or_doc('src', r'matrix\(', 'incidence_structures', 'self', 'combinat', interact=False).splitlines()) > 1  # optional - sagemath_doc_html
+        sage: from sage.misc.sagedoc import _search_src_or_doc
+        sage: len(_search_src_or_doc('src', r'matrix\(', 'incidence_structures', 'self', 'combinat', interact=False).splitlines()) > 1
         True
         sage: 'abvar/homology' in _search_src_or_doc('doc', 'homology', 'variety', interact=False)  # optional - sagemath_doc_html, long time (4s on sage.math, 2012)
         True
-        sage: 'divisors' in _search_src_or_doc('src', '^ *def prime', interact=False)  # optional - sagemath_doc_html
+        sage: 'divisors' in _search_src_or_doc('src', '^ *def prime', interact=False)
         True
 
     When passing ``interactive=True``, in a terminal session this will pass the
@@ -1369,7 +1369,7 @@ class _sage_doc:
 
         sage: browse_sage_doc._open("reference", testing=True)[0]  # optional - sagemath_doc_html, indirect doctest
         'http://localhost:8000/doc/live/reference/index.html'
-        sage: browse_sage_doc(identity_matrix, 'rst')[-107:-47]  # optional - sagemath_doc_html
+        sage: browse_sage_doc(identity_matrix, 'rst')[-107:-47]
         'Full MatrixSpace of 3 by 3 sparse matrices over Integer Ring'
     """
     def __init__(self):

src/sage_docbuild/__init__.py

@@ -105,7 +105,7 @@ def builder_helper(type):
         sage: from sage_docbuild import builder_helper, build_ref_doc
         sage: from sage_docbuild import _build_many as build_many
         sage: helper = builder_helper("html")
-        sage: try:
+        sage: try:  # optional - sagemath_doc_html
         ....:     build_many(build_ref_doc, [("docname", "en", "html", {})])
         ....: except Exception as E:
         ....:     "Non-exception during docbuild: abort pool operation" in str(E)
@@ -186,7 +186,7 @@ def _output_dir(self, type):
 
             sage: from sage_docbuild import DocBuilder
             sage: b = DocBuilder('tutorial')
-            sage: b._output_dir('html')
+            sage: b._output_dir('html')         # optional - sagemath_doc_html
             '.../html/en/tutorial'
         """
         d = os.path.join(SAGE_DOC, type, self.lang, self.name)
@@ -203,7 +203,7 @@ def _doctrees_dir(self):
 
             sage: from sage_docbuild import DocBuilder
             sage: b = DocBuilder('tutorial')
-            sage: b._doctrees_dir()
+            sage: b._doctrees_dir()             # optional - sagemath_doc_html
             '.../doctrees/en/tutorial'
         """
         d = os.path.join(SAGE_DOC, 'doctrees', self.lang, self.name)
@@ -483,7 +483,7 @@ def _output_dir(self, type, lang=None):
 
             sage: from sage_docbuild import ReferenceBuilder
             sage: b = ReferenceBuilder('reference')
-            sage: b._output_dir('html')
+            sage: b._output_dir('html')         # optional - sagemath_doc_html
             '.../html/en/reference'
         """
         if lang is None:
@@ -594,7 +594,7 @@ def _output_dir(self, type, lang=None):
 
             sage: from sage_docbuild import ReferenceTopBuilder
             sage: b = ReferenceTopBuilder('reference')
-            sage: b._output_dir('html')
+            sage: b._output_dir('html')         # optional - sagemath_doc_html
             '.../html/en/reference'
         """
         if lang is None: