From 7f3fc736f5b0ffc855a44cc998f9eef45190ff0c Mon Sep 17 00:00:00 2001
From: Andreas Kloeckner <inform@tiker.net>
Date: Sun, 19 Jun 2022 18:20:41 -0500
Subject: [PATCH] Make name of doc build flag more global, explain
---
arraycontext/impl/pytato/__init__.py | 2 +-
doc/conf.py | 11 ++++++++++-
2 files changed, 11 insertions(+), 2 deletions(-)
diff --git a/arraycontext/impl/pytato/__init__.py b/arraycontext/impl/pytato/__init__.py
index 8d87b86..0970ffb 100644
--- a/arraycontext/impl/pytato/__init__.py
+++ b/arraycontext/impl/pytato/__init__.py
@@ -58,7 +58,7 @@ if TYPE_CHECKING:
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
diff --git a/doc/conf.py b/doc/conf.py
index c915724..84a6d64 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -27,5 +27,14 @@ intersphinx_mapping = {
"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
--
GitLab