Add and use HideReason enum

Author: robtaylor

autoapi/_mapper.py

@@ -30,6 +30,7 @@
     PythonData,
     PythonException,
     _trace_visibility,
+    HideReason,
 )
 from .settings import OWN_PAGE_LEVELS, TEMPLATE_DIR
 
@@ -389,13 +390,6 @@ def _output_top_rst(self):
         # Render Top Index
         top_level_index = os.path.join(self.dir_root, "index.rst")
 
-        modules = [obj for obj in self.all_objects.values()
-                   if obj.type == "module" and obj.docstring == ""]
-        if modules and "undoc-members" not in self.app.config.autoapi_options:
-            _color_info("The following modules have no top-level documentation, and so were skipped as undocumented:")
-            for m in modules:
-                _color_info(f"    {m.id}")
-
         pages = [obj for obj in self.objects_to_render.values() if obj.display]
         if not pages:
             msg = (
@@ -508,7 +502,7 @@ def _skip_if_stdlib(self):
                     and module not in documented_modules
                 ):
                     _trace_visibility(self.app, f"Hiding {obj['qual_name']} as determined to be Python standard Library (found as {obj['full_name']})", verbose=2)
-                    obj["hide"] = True
+                    obj["hide_reasom"] = HideReason.STD_LIBRARY
 
     def _resolve_placeholders(self):
         """Resolve objects that have been imported from elsewhere."""
@@ -527,19 +521,18 @@ def _hide_yo_kids(self):
         for module in self.paths.values():
             if module["all"] is not None:
                 all_names = set(module["all"])
-                _trace_visibility(self.app, f"{module['full_name']}: Found __all__ =")
                 for n in all_names:
                     _trace_visibility(self.app, f"    {n}")
                 for child in module["children"]:
                     if child["qual_name"] not in all_names:
                         _trace_visibility(self.app, f"Hiding {child['full_name']}, as {child['qual_name']} not in __all__")
-                        child["hide"] = True
+                        child["hide_reason"] = HideReason.NOT_IN_ALL
             elif module["type"] == "module":
                 _trace_visibility(self.app, f"Testing if any children of {module['full_name']} have already been documented")
                 for child in module["children"]:
                     if "original_path" in child:
-                        _trace_visibility(self.app, f"Hiding {child['full_name']} as documented at {child['original_path']}")
-                        child["hide"] = True
+                        _trace_visibility(self.app, f"Hiding {child['full_name']} as it appears to be in your public API at {child['original_path']}")
+                        child["hide_reason"] = HideReason.NOT_PUBLIC
 
     def map(self, options=None):
         self._skip_if_stdlib()
@@ -583,17 +576,17 @@ def _render_selection(self):
                 self.objects_to_render[obj.id] = obj
             else:
                 if obj.subpackages or obj.submodules:
-                    _trace_visibility(self.app, f"Not rendering the following as {obj.id} set to not display:", verbose=2)
+                    _trace_visibility(self.app, f"Not rendering the following as {obj.id} set to not display because object is {obj.hide_reason}", verbose=2)
                 for module in itertools.chain(obj.subpackages, obj.submodules):
                     _trace_visibility(self.app, f"    {module.obj['full_name']}", verbose=2)
-                    module.obj["hide"] = True
+                    module.obj["hide_reason"] = HideReason.PARENT_HIDDEN
 
         def _inner(parent):
             for child in parent.children:
                 self.all_objects[child.id] = child
                 if not parent.display:
                     _trace_visibility(self.app, f"Hiding {child.id} as parent {parent.id} will not be displayed", verbose=2)
-                    child.obj["hide"] = True
+                    child.obj["hide_reason"] = HideReason.PARENT_HIDDEN
 
                 if child.display and child.type in self.own_page_types:
                     self.objects_to_render[child.id] = child
@@ -603,6 +596,15 @@ def _inner(parent):
         for obj in list(self.all_objects.values()):
             _inner(obj)
 
+        modules = [obj for obj in self.all_objects.values()
+                   if obj.type == "module" and obj.docstring == ""]
+        if modules and "undoc-members" not in self.app.config.autoapi_options:
+            _color_info("The following modules have no top-level documentation, and so were skipped as undocumented:")
+            for m in modules:
+                _color_info(f"    {m.id}")
+
+
+
     def create_class(self, data, options=None):
         """Create a class from the passed in data
 

autoapi/_objects.py

@@ -3,6 +3,9 @@
 import functools
 import pathlib
 
+from enum import StrEnum, auto
+from typing import List
+
 import sphinx
 import sphinx.util
 import sphinx.util.logging
@@ -34,6 +37,18 @@ def _format_args(args_info, include_annotations=True, ignore_self=None):
 
     return ", ".join(result)
 
+class HideReason(StrEnum):
+    NOT_HIDDEN = "not hidden"
+    UNDOC_MEMBER = "undocumented"
+    PRIVATE_MEMBER = "a private member"
+    SPECIAL_MEMBER = "a special member"
+    IMPORTED_MEMBER = "an imported member"
+    INHERITED_MEMBER = "an inherited member"
+    IS_NEW_OR_INIT = "__new__ or __init__"
+    NOT_IN_ALL = "not in __all__ for module"
+    PARENT_HIDDEN = "parent is hidden"
+    STD_LIBRARY = "part of Python standard library"
+
 
 class PythonObject:
     """A class representing an entity from the parsed source code.
@@ -50,7 +65,7 @@ class PythonObject:
     type: str
 
     def __init__(
-        self, obj, jinja_env, app, url_root, options=None, class_content="class"
+            self, obj, jinja_env, app, url_root, options: List[str]=[], class_content="class"
     ):
         self.app = app
         self.obj = obj
@@ -85,7 +100,7 @@ def __init__(
         # For later
         self._class_content = class_content
         self._display_cache: bool | None = None
-        self._skip_reason = None
+        self._skip_reason = ""
 
     def __getstate__(self):
         """Obtains serialisable data for pickling."""
@@ -199,20 +214,54 @@ def is_special_member(self) -> bool:
         """Whether this object is a special member (True) or not (False)."""
         return self.short_name.startswith("__") and self.short_name.endswith("__")
 
+    @property
+    def hide_reason(self) -> HideReason:
+        skip_undoc_member = self.is_undoc_member and "undoc-members" not in self.options
+        skip_private_member = (
+            self.is_private_member and "private-members" not in self.options
+        )
+        skip_special_member = (
+            self.is_special_member and "special-members" not in self.options
+        )
+        skip_imported_member = self.imported and "imported-members" not in self.options
+        skip_inherited_member = (
+            self.inherited and "inherited-members" not in self.options
+        )
+
+        reason = HideReason.NOT_HIDDEN
+        if self.obj.get("hide", False):
+            reason = HideReason.MARKED_HIDDEN
+        elif skip_undoc_member:
+            reason = HideReason.UNDOC_MEMBER
+        elif skip_private_member:
+            reason = HideReason.UNDOC_MEMBER
+        elif skip_special_member:
+            reason = HideReason.SPECIAL_MEMBER
+        elif skip_imported_member:
+            reason = HideReason.IMPORTED_MEMBER
+        elif  skip_inherited_member:
+            reason = HideReason.INHERITED_MEMBER
+
+        self._skip_reason = f"Skipping {self.id} as object is {reason}"
+
+        return reason
+
+
     @property
     def display(self) -> bool:
         """Whether this object should be displayed in documentation.
 
         This attribute depends on the configuration options given in
         :confval:`autoapi_options` and the result of :event:`autoapi-skip-member`.
         """
-        skip = self._should_skip()
+        skip = self.hide_reason != HideReason.NOT_HIDDEN
+
         if self._display_cache is None:
             self._display_cache = not self._ask_ignore(skip)
             if self._display_cache is False:
                 _trace_visibility(self.app, self._skip_reason)
         else:
-            _trace_visibility(self.app, f"Skipping {self.id} due to cache", verbose=2)
+            _trace_visibility(self.app, f"Skipping {self.id} due to {self.hide_reason}", verbose=2)
 
         return self._display_cache
 
@@ -230,44 +279,6 @@ def summary(self) -> str:
 
         return ""
 
-    def _should_skip(self) -> bool:
-        skip_undoc_member = self.is_undoc_member and "undoc-members" not in self.options
-        skip_private_member = (
-            self.is_private_member and "private-members" not in self.options
-        )
-        skip_special_member = (
-            self.is_special_member and "special-members" not in self.options
-        )
-        skip_imported_member = self.imported and "imported-members" not in self.options
-        skip_inherited_member = (
-            self.inherited and "inherited-members" not in self.options
-        )
-
-        reason = ""
-        if self.obj.get("hide", False):
-            reason = "marked hidden by mapper"
-        elif skip_undoc_member:
-            reason = "is undocumented"
-        elif skip_private_member:
-            reason = "is a private member"
-        elif skip_special_member:
-            reason = "is a special member"
-        elif skip_imported_member:
-            reason = "is an imported member"
-        elif  skip_inherited_member:
-            reason = "is an inherited member"
-
-        self._skip_reason = f"Skipping {self.id} as {reason}"
-
-        return (
-            self.obj.get("hide", False)
-            or skip_undoc_member
-            or skip_private_member
-            or skip_special_member
-            or skip_imported_member
-            or skip_inherited_member
-        )
-
     def _ask_ignore(self, skip: bool) -> bool:
 
         ask_result = self.app.emit_firstresult(
@@ -339,14 +350,17 @@ def __init__(self, *args, **kwargs):
         Can be any of: abstractmethod, async, classmethod, property, staticmethod.
         """
 
-    def _should_skip(self) -> bool:
+    @property
+    def hide_reason(self) -> HideReason:
         is_new_or_init = self.name in (
             "__new__",
             "__init__",
         )
-        if not super()._should_skip and is_new_or_init:
+        hide_reason = super().hide_reason
+        if hide_reason != HideReason.NOT_HIDDEN and is_new_or_init:
             self._skip_reason = f"Skipping method {self.id} as is __new__ or __init__"
-        return super()._should_skip() or is_new_or_init
+            return HideReason.IS_NEW_OR_INIT
+        return hide_reason
 
 class PythonProperty(PythonObject):
     """The representation of a property on a class."""