Merge pull request #3680 from jsiirola/building-docs-test

Docs: rework logic in `building_documentation()`

Author: blnicho

doc/OnlineDocs/conf.py

@@ -38,6 +38,13 @@
 # our sphinx extensions
 sys.path.insert(0, os.path.abspath('ext'))
 
+# -- Mark that we are running Sphinx --------------------------------------
+import pyomo
+
+# Mark a "convenient" and reasonably unique global flag that we can use
+# elsewhere to reliably tell if Sphinx is building / testing the docs
+pyomo.__sphinx_build__ = True
+
 # -- Rebuild SPY files ----------------------------------------------------
 sys.path.insert(0, os.path.abspath('src'))
 try:

doc/OnlineDocs/ext/pyomo_autosummary_autoenum.py

@@ -20,13 +20,13 @@
 
 from sphinx.application import Sphinx
 from sphinx.domains import ObjType
-from sphinx.domains.python import PyClasslike, PyAttribute, PyXRefRole
+from sphinx.domains.python import PyClasslike, PyXRefRole
 from sphinx.ext import autodoc, autosummary
 from sphinx.ext.autosummary import mangle_signature as _msig
 from sphinx.ext.autosummary.generate import generate_autosummary_content as _gac
 from sphinx.util.inspect import object_description
-from sphinx_toolbox.more_autodoc.typehints import format_annotation
-from typing import Type, Any, Dict, List, Tuple, Union
+from sphinx.util.typing import restify
+from typing import Any, Dict, List, Tuple
 
 _pre_re = re.compile(r'^( = )(.*)')
 
@@ -129,7 +129,7 @@ def render(self, name, ns):
                     for _base in mro[: mro.index(enum.Enum)]:
                         if not isinstance(_base, enum.EnumMeta):
                             ns['member_type'] = (
-                                f"Member type: {format_annotation(_base)}"
+                                f"Member type: {restify(_base, mode='smart')}"
                             )
                             break
                 return super().render(name, ns)

pyomo/common/flags.py

@@ -8,7 +8,7 @@
 #  rights in this software.
 #  This software is distributed under the 3-clause BSD License.
 #  ___________________________________________________________________________
-
+import pyomo
 import inspect
 import sys
 
@@ -115,7 +115,13 @@ def building_documentation(state=NOTSET):
         building_documentation.state = state
     if building_documentation.state is not None:
         return bool(building_documentation.state)
-    return 'sphinx' in sys.modules or 'Sphinx' in sys.modules
+    # Note that we previously detected if Sphinx was running by looking
+    # for it in sys.modules.  That proved to be fragile as other
+    # packages (notably sphinx-jinja2-compat) started causing Sphinx to
+    # be imported immediately any time Python started.  We work around
+    # this by having Pyomo's Sphinx conf.py add a flag to an
+    # easy-to-find location.
+    return bool(getattr(pyomo, '__sphinx_build__', False))
 
 
 building_documentation.state = None

pyomo/common/tests/test_flags.py

@@ -11,6 +11,7 @@
 
 import sys
 
+import pyomo
 import pyomo.common.unittest as unittest
 
 from pyomo.common.flags import NOTSET, in_testing_environment, building_documentation
@@ -23,12 +24,12 @@ def test_NOTSET(self):
         self.assertFalse(building_documentation())
 
         self.assertEqual(str(NOTSET), 'NOTSET')
-        self.assertNotIn('sphinx', sys.modules)
+        self.assertFalse(hasattr(pyomo, '__sphinx_build__'))
         self.assertEqual(repr(NOTSET), 'pyomo.common.flags.NOTSET')
         self.assertIsNone(in_testing_environment.state)
 
         try:
-            sys.modules['sphinx'] = sys.modules[__name__]
+            pyomo.__sphinx_build__ = True
             self.assertTrue(in_testing_environment())
             self.assertTrue(building_documentation())
             self.assertEqual(repr(NOTSET), 'NOTSET')
@@ -38,7 +39,7 @@ def test_NOTSET(self):
             self.assertTrue(building_documentation())
             self.assertEqual(repr(NOTSET), 'NOTSET')
         finally:
-            del sys.modules['sphinx']
+            del pyomo.__sphinx_build__
             in_testing_environment(None)
         self.assertIsNone(in_testing_environment.state)
 

setup.py

@@ -219,8 +219,6 @@ def __ne__(self, other):
             'sphinx_rtd_theme>0.5',
             'sphinxcontrib-jsmath',
             'sphinxcontrib-napoleon',
-            'sphinx-toolbox>=2.16.0',
-            'sphinx-jinja2-compat>=0.1.1',
             'numpy',  # Needed by autodoc for pynumero
             'scipy',  # Needed by autodoc for pynumero
         ],