maint: move patching for autodoc from setup.py to doc/conf.py.

Author: carandraug

doc/conf.py

@@ -8,13 +8,74 @@
 ## notice and this notice are preserved.  This file is offered as-is,
 ## without any warranty.
 
+import ctypes
 import datetime
 import sys
+import unittest.mock
 
 
 sys.path.insert(0, "../microscope")
 
 
+# autodoc imports the modules to be documented.  Modules that wrap the
+# device C libraries will load that library.  This would require all
+# device libraries to be available to build the documentation.
+# autodoc can mocks different modules (see `autodoc_mock_imports`) but
+# that's not enough for all of our cases.
+
+
+def patch_cdll():
+    real_c_dll = ctypes.CDLL
+
+    mocked_c_libs = [
+        # Andor's SDK for (EM)CCD cameras.  Loading of this libary
+        # should be in a separate microcope._wrappers.atmcd module and
+        # then autodoc could just mock it.
+        "atmcd32d",
+        "atmcd32d.so",
+        "atmcd64d",
+        "atmcd64d.so",
+        # pvcam's SDK.  Loading of this shared library should be in a
+        # separate microcope._wrappers.pvcam module and then autodoc
+        # could just mock it.
+        "pvcam.so",
+        "pvcam32",
+        "pvcam64",
+    ]
+
+    def cdll_diversion(name, *args, **kwargs):
+        if name in mocked_c_libs:
+            return unittest.mock.MagicMock()
+        else:
+            return real_c_dll(name, *args, **kwargs)
+
+    ctypes.WinDLL = cdll_diversion
+    ctypes.CDLL = cdll_diversion
+
+
+patch_cdll()
+
+
+def patch_sizeof():
+    # autodoc is mocking microscope._wrappers.dcamapi4 but we create
+    # one of these structs for a singleton.
+    real_sizeof = ctypes.sizeof
+
+    def sizeof_diversion(struct):
+        if (
+            hasattr(struct, "___sphinx_mock__")
+            and str(struct) == "microscope._wrappers.dcamapi4.API_INIT"
+        ):
+            return 40  # doesn't really matter
+        else:
+            return real_sizeof(struct)
+
+    ctypes.sizeof = sizeof_diversion
+
+
+patch_sizeof()
+
+
 # This should ve read from setup.py.  Maybe we should use
 # pkg_resources to avoid duplication?
 author = ""

setup.py

@@ -8,9 +8,7 @@
 ## notice and this notice are preserved.  This file is offered as-is,
 ## without any warranty.
 
-import ctypes
 import distutils.cmd
-import unittest.mock
 
 import setuptools
 import setuptools.command.sdist
@@ -32,36 +30,6 @@
     has_sphinx = False
 
 
-# List of C libraries that microscope can make use of, and may be
-# required to support specific devices.  We need to create stubs of
-# them to build the documentation.  Their names here are their name
-# when used to construct ctypes' CDLL and WinDLL.
-optional_c_libs = [
-    # Alpao SDK
-    "ASDK",
-    "libasdk.so",
-    # Andor's atcore (SDK3)
-    "atcore",
-    "atcore.so",
-    # Andor's SDK for (EM)CCD cameras
-    "atmcd32d",
-    "atmcd32d.so",
-    "atmcd64d",
-    "atmcd64d.so",
-    # Andor's atutility (SDK3)
-    "atutility",
-    "atutility.so",
-    # Boston Micromachines Corporation (BMC) SDK
-    "BMC",
-    "libBMC.so.3",
-    # Mirao52e SDK (windows only)
-    "mirao52e",
-    # pvcam's SDK
-    "pvcam.so",
-    "pvcam32",
-    "pvcam64",
-]
-
 # Shadow the sphinx provided command, in order to run sphinx-apidoc
 # before sphinx-build.  This builds the rst files with the actual
 # package inline documentation.
@@ -79,60 +47,33 @@
 
         apidoc_ini_args = ["sphinx-apidoc"]
 
-    # Building the documentation using the module docstrings causes
-    # the modules to be imported.  Modules that wrap the optional C
-    # libraries will try to access the library functions, which means
-    # that those optional C libraries are required to build the
-    # documentation.  So we patch ctypes.CDLL to intercept a request
-    # for those libraries and inject a stub instead.
-    #
-    # At import time, some of our modules will also make calls to
-    # functions in the optional C libraries.  Because of this, a stub
-    # for the library is not enough, those functions will need to
-    # behave well enough to not cause an error during import.
-    stub_c_attrs = {
-        "AT_InitialiseLibrary.return_value": 0,  # AT_SUCCESS
-        "AT_InitialiseUtilityLibrary.return_value": 0,  # AT_SUCCESS
-    }
-    stub_c_dll = unittest.mock.MagicMock()
-    stub_c_dll.configure_mock(**stub_c_attrs)
-
-    real_c_dll = ctypes.CDLL
-
-    def cdll_diversion(name, *args, **kwargs):
-        if name in optional_c_libs:
-            return stub_c_dll
-        else:
-            return real_c_dll(name, *args, **kwargs)
-
     class BuildDoc(sphinx.setup_command.BuildDoc):
         def run(self):
             apidoc.main(
                 apidoc_ini_args
                 + [
                     "--separate",  # each module on its own page
+                    "--private",  # include private modules
                     "--module-first",
                     "--tocfile",
                     "index",
                     "--output-dir",
                     "doc/api",
                     "microscope",
-                    # exclude win32 so docs will build on other platforms
-                    "microscope/win32.py",
                     # exclude the testsuite
                     "microscope/testsuite/",
+                    # exclude the wrappers to shared libraries
+                    "microscope/_wrappers/",
                     # exclude the deprecated devices and deviceserver that
                     # are kept for backwards compatibility only.
                     "microscope/devices.py",
                     "microscope/deviceserver.py",
+                    "microscope/lasers/",
+                    "microscope/cameras/_SDK3.py",
+                    "microscope/cameras/_SDK3Cam.py",
                 ]
             )
-
-            with unittest.mock.patch("ctypes.CDLL", new=cdll_diversion):
-                with unittest.mock.patch(
-                    "ctypes.WinDLL", new=cdll_diversion, create=True
-                ):
-                    super().run()
+            super().run()
 
 else:
 
@@ -215,5 +156,8 @@ def make_distribution(self):
             "source_dir": ("setup.py", "doc"),
         },
     },
-    cmdclass={"build_sphinx": BuildDoc, "sdist": sdist},
+    cmdclass={
+        "build_sphinx": BuildDoc,
+        "sdist": sdist,
+    },
 )