Make sure PathListCache is in API docs

CHANGES.txt

@@ -54,8 +54,10 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - Handle the default (unset) ProgressObject differently for the sole
       purpose of avoiding Sphinx 9.0+ blowing up on it (it's been giving
       a warning for years, but now it's a fatal error).
-    - Improve coverage of API doc build by ignoring any setting of
+    - Improve coverage of "API docs" build by ignoring any setting of
       __all__ in a package and not showing inherited members from optparse.
+      Add a trick to make sure the build sees PathListCache while
+      generating docs (in normal operation, it's removed so was not visible).
     - Fix --debug=includes for case of multiple source files.
     - Unify internal "_null" sentinel usage.
     - All functions/classes/non-dunder methods in Environment have docstrings.

RELEASE.txt

@@ -110,8 +110,10 @@ DOCUMENTATION
   a warning for years, but now it's a fatal error). Affects only the
   API doc build.
 
-- Improve coverage of API doc build by ignoring any setting of
+- Improve coverage of "API doc" build by ignoring any setting of
   __all__ in a package and not showing inherited members from optparse.
+  Add a trick to make sure build sees PathListCache while generating
+  docs (in normal operation, it's removed so was not visible).
 
 - All functions/classes/non-dunder methods in Environment now have docstrings.
 

SCons/PathList.py

@@ -30,6 +30,7 @@
 """
 
 import os
+import sys
 
 import SCons.Memoize
 import SCons.Node
@@ -216,6 +217,7 @@ def PathList(self, pathlist, split=True):
 
 PathList = PathListCache().PathList
 
-# TODO: removing the class object here means Sphinx doesn't pick up its
-#   docstrings: they're fine for reading here, but are not in API Docs.
-del PathListCache
+# Some trickery here so Sphinx can still see the class when building API docs
+_SPHINX_BUILD = os.environ.get("SPHINX_BUILD") == "1"
+if not _SPHINX_BUILD:
+    del PathListCache

doc/sphinx/conf.py

@@ -23,6 +23,9 @@
 sys.path.insert(0, os.path.abspath('../../bin'))
 sys.path.insert(0, os.path.abspath('../../'))
 
+# Set a marker in case code needs to know it's running under sphinx-build
+os.environ.setdefault("SPHINX_BUILD", "1")
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.