FEAT: generate API for multiple packages (#12)

* DX: activate VSCode multi-file diff editor
  https://code.visualstudio.com/updates/v1_85\#_multifile-diff-editor
* MAINT: autoupdate pre-commit hooks

Author: redeboer

.pre-commit-config.yaml

@@ -45,7 +45,7 @@ repos:
       - id: blacken-docs
 
   - repo: https://github.com/ComPWA/repo-maintenance
-    rev: 0.1.7
+    rev: 0.1.9
     hooks:
       - id: check-dev-files
         args:
@@ -56,7 +56,7 @@ repos:
           - --repo-title=sphinx-api-relink
 
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: v8.0.0
+    rev: v8.1.1
     hooks:
       - id: cspell
 
@@ -81,17 +81,17 @@ repos:
           - python
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v4.0.0-alpha.3
+    rev: v4.0.0-alpha.3-1
     hooks:
       - id: prettier
 
   - repo: https://github.com/ComPWA/mirrors-pyright
-    rev: v1.1.338
+    rev: v1.1.339
     hooks:
       - id: pyright
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.6
+    rev: v0.1.7
     hooks:
       - id: ruff
         args: [--fix]

.vscode/settings.json

@@ -45,6 +45,7 @@
   "git.rebaseWhenSync": true,
   "github-actions.workflows.pinned.refresh.enabled": true,
   "github-actions.workflows.pinned.workflows": [".github/workflows/ci.yml"],
+  "multiDiffEditor.experimental.enabled": true,
   "mypy-type-checker.args": ["--config-file=${workspaceFolder}/pyproject.toml"],
   "mypy-type-checker.importStrategy": "fromEnvironment",
   "python.analysis.autoImportCompletions": false,

README.md

@@ -65,6 +65,15 @@ To generate the API for [`sphinx.ext.autodoc`](https://www.sphinx-doc.org/en/mas
 generate_apidoc_package_path = "../src/my_package"  # relative to conf.py
 ```
 
+Multiple packages can be listed as well:
+
+```python
+generate_apidoc_package_path = [
+    "../src/package1",
+    "../src/package2",
+]
+```
+
 The API is generated with the same style used by the ComPWA repositories (see e.g. [ampform.rtfd.io/en/stable/api/ampform.html](https://ampform.readthedocs.io/en/stable/api/ampform.html)). To use the default template, set:
 
 ```python

src/sphinx_api_relink/__init__.py

@@ -46,17 +46,23 @@ def set_linkcode_resolve(app: Sphinx, _: BuildEnvironment) -> None:
 
 def generate_apidoc(app: Sphinx, _: BuildEnvironment) -> None:
     config_key = "generate_apidoc_package_path"
-    package_path: str | None = getattr(app.config, config_key, None)
+    package_path: list[str] | str | None = getattr(app.config, config_key, None)
     if package_path is None:
         return
-    abs_package_path = Path(app.srcdir) / package_path
     apidoc_dir = Path(app.srcdir) / app.config.generate_apidoc_directory
-    _run_sphinx_apidoc(
-        abs_package_path,
-        apidoc_dir,
-        excludes=app.config.generate_apidoc_excludes,
-        use_compwa_template=app.config.generate_apidoc_use_compwa_template,
-    )
+    shutil.rmtree(apidoc_dir, ignore_errors=True)
+    if isinstance(package_path, str):
+        package_dirs = [package_path]
+    else:
+        package_dirs = package_path
+    for rel_dir in package_dirs:
+        abs_package_path = Path(app.srcdir) / rel_dir
+        _run_sphinx_apidoc(
+            abs_package_path,
+            apidoc_dir,
+            excludes=app.config.generate_apidoc_excludes,
+            use_compwa_template=app.config.generate_apidoc_use_compwa_template,
+        )
 
 
 def _run_sphinx_apidoc(
@@ -68,7 +74,6 @@ def _run_sphinx_apidoc(
     if not package_path.exists():
         msg = f"Package under {package_path} does not exist"
         raise FileNotFoundError(msg)
-    shutil.rmtree(apidoc_dir, ignore_errors=True)
     args: list[str] = [str(package_path)]
     if excludes is None:
         excludes = []