Fail better in ExceptionDocumenter.can_document_member (#11660)

jamesbraza · AA-Turner · web-flow · commit 74329d9c51c1 · 2023-08-30T18:49:27.000Z
Co-authored-by: Adam Turner &lt;9087854+aa-turner@users.noreply.github.com&gt;
diff --git a/CHANGES b/CHANGES
@@ -24,6 +24,10 @@ Bugs fixed
   for sibling files in a subdirectory.
   Patch by Albert Shih.
 * #11659: Allow ``?config=...`` in :confval:`mathjax_path`.
+* #11654: autodoc: Fail with a more descriptive error message
+  when an object claims to be an instance of ``type``,
+  but is not a class.
+  Patch by  James Braza.
 
 Testing
 -------
diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
@@ -1913,7 +1913,17 @@ class ExceptionDocumenter(ClassDocumenter):
     @classmethod
     def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any,
                             ) -> bool:
-        return isinstance(member, type) and issubclass(member, BaseException)
+        try:
+            return isinstance(member, type) and issubclass(member, BaseException)
+        except TypeError as exc:
+            # It's possible for a member to be considered a type, but fail
+            # issubclass checks due to not being a class. For example:
+            # https://github.com/sphinx-doc/sphinx/issues/11654#issuecomment-1696790436
+            msg = (
+                f'{cls.__name__} failed to discern if member {member} with'
+                f' membername {membername} is a BaseException subclass.'
+            )
+            raise ValueError(msg) from exc
 
 
 class DataDocumenterMixinBase:
