Make name of doc build flag more global, explain

Author: inducer

arraycontext/impl/pytato/__init__.py

@@ -58,7 +58,7 @@
     import pytato
     import pyopencl as cl
 
-if getattr(sys, "ARRAYCONTEXT_BUILDING_SPHINX_DOCS", False):
+if getattr(sys, "_BUILDING_SPHINX_DOCS", False):
     import pyopencl as cl  # noqa: F811
 
 

doc/conf.py

@@ -27,5 +27,14 @@
     "https://jax.readthedocs.io/en/latest/": None,
 }
 
+# Some modules need to import things just so that sphinx can resolve symbols in
+# type annotations. Often, we do not want these imports (e.g. of PyOpenCL) when
+# in normal use (because they would introduce unintended side effects or hard
+# dependencies). This flag exists so that these imports only occur during doc
+# build. Since sphinx appears to resolve type hints lexically (as it should),
+# this needs to be cross-module (since, e.g. an inherited arraycontext
+# docstring can be read by sphinx when building meshmode, a dependent package),
+# this needs a setting of the same name across all packages involved, that's
+# why this name is as global-sounding as it is.
 import sys
-sys.ARRAYCONTEXT_BUILDING_SPHINX_DOCS = True
+sys._BUILDING_SPHINX_DOCS = True