✨ Add autodoc2_packages[autodoc] option

To turn off generating documentation

Author: chrisjsewell

docs/apidocs/autodoc2/autodoc2.config.rst

@@ -123,6 +123,13 @@ API
 
       .. autodoc2-docstring:: autodoc2.config.PackageConfig.exclude_files
 
+   .. py:attribute:: autodoc
+      :canonical: autodoc2.config.PackageConfig.autodoc
+      :type: bool
+      :value: None
+
+      .. autodoc2-docstring:: autodoc2.config.PackageConfig.autodoc
+
    .. py:method:: as_triple() -> typing.Iterable[tuple[str, typing.Any, dataclasses.Field]]
       :canonical: autodoc2.config.PackageConfig.as_triple
 

src/autodoc2/config.py

@@ -57,6 +57,13 @@ class PackageConfig:
         },
     )
 
+    autodoc: bool = dc.field(
+        default=True,
+        metadata={
+            "help": "Whether to generate documentation for the package.",
+        },
+    )
+
     def as_triple(self) -> t.Iterable[tuple[str, t.Any, dc.Field]]:  # type: ignore[type-arg]
         """Yield triples of (name, value, field)."""
         fields = {f.name: f for f in dc.fields(self.__class__)}
@@ -73,6 +80,7 @@ def _coerce_packages(name: str, item: t.Any) -> list[PackageConfig]:
     # make sure we don't mutate the original (triggers sphinx total rebuild)
     new = [deepcopy(i) for i in item]
     for i, package in enumerate(new[:]):
+        # TODO here we should use the PackageConfig to validate
         if isinstance(package, str):
             new[i] = package = {"path": package}
         if not isinstance(package, dict):
@@ -105,6 +113,8 @@ def _coerce_packages(name: str, item: t.Any) -> list[PackageConfig]:
                 or not all(isinstance(x, str) for x in package[key])
             ):
                 raise ValidationError(f"{name}[{i}][{key!r}] must be a list of strings")
+        if "autodoc" in package and not isinstance(package["autodoc"], bool):
+            raise ValidationError(f"{name}[{i}]['autodoc'] must be a boolean")
 
     return [PackageConfig(**p) for p in new]
 

src/autodoc2/sphinx/extension.py

@@ -176,6 +176,13 @@ def run_autodoc_package(app: Sphinx, config: Config, pkg_index: int) -> str | No
                     )
         autodoc2_cache[path.as_posix()] = {"hash": hash_str, "db": db}
 
+    output = Path(app.srcdir) / PurePosixPath(config.output_dir) / root_module
+
+    if not package.autodoc:
+        if output.exists() and output.is_dir():
+            shutil.rmtree(output)
+        return None
+
     # find all the package/module, so we know what files to write
     LOGGER.info("[Autodoc2] Determining files to write ...")
     to_write: t.List[str] = []
@@ -195,7 +202,6 @@ def _warn_render(msg: str, type_: WarningSubtypes) -> None:
         warn_sphinx(msg, type_)
 
     # write the files
-    output = Path(app.srcdir) / PurePosixPath(config.output_dir) / root_module
     output.mkdir(parents=True, exist_ok=True)
     paths = []
     for mod_name in status_iterator(