Support documenting namespace packages

src/autodoc2/analysis.py

@@ -13,7 +13,7 @@
 import typing as t
 
 from astroid import nodes
-from astroid.builder import AstroidBuilder
+from astroid.builder import AstroidBuilder, build_namespace_package_module
 
 from . import astroid_utils
 
@@ -37,7 +37,10 @@ def analyse_module(
         you can use this to record them.
     """
     # TODO expose record_external_imports everywhere analyse_module is used
-    node = AstroidBuilder().file_build(os.fsdecode(file_path), name)
+    if not file_path.is_dir():
+        node = AstroidBuilder().file_build(os.fsdecode(file_path), name)
+    else:
+        node = build_namespace_package_module(name, file_path.parts)
     yield from walk_node(
         node, State(node.name.split(".", 1)[0], [], exclude_external_imports)
     )

src/autodoc2/sphinx/extension.py

@@ -139,7 +139,8 @@ def run_autodoc_package(app: Sphinx, config: Config, pkg_index: int) -> str | No
     # so we can check if we need to re-analyse them
     hasher = hashlib.sha256()
     for mod_path, _ in sorted(modules):
-        hasher.update(mod_path.read_bytes())
+        if mod_path.is_file():
+            hasher.update(mod_path.read_bytes())
     hash_str = hasher.hexdigest()
 
     if (

src/autodoc2/utils.py

@@ -107,8 +107,15 @@ def _suffix_sort_key(s: str) -> int:
             name, suffix = os.path.splitext(filename)
             if suffix in extensions:
                 to_yield.setdefault(name, []).append(suffix)
+
         root_path = Path(root)
         rel_mod = root_path.relative_to(folder).parts
+
+        # This is a namespace module.
+        if "__init__.py" not in filenames:
+            yield (root_path, ".".join([*root_mod, *rel_mod]))
+        # Otherwise, the specific `__init__.py` file will be included
+        # below.
         for name, suffixes in to_yield.items():
             suffix = sorted(suffixes, key=_suffix_sort_key)[0]
             yield (root_path / f"{name}{suffix}", ".".join([*root_mod, *rel_mod, name]))