also generate index.md for __init__.py files

manage_docs.py

@@ -27,7 +27,6 @@ Optional flags:
 from __future__ import annotations
 
 import argparse
-import sys
 from pathlib import Path
 
 from mkdocs.commands import build as mkdocs_build
@@ -40,6 +39,7 @@ DEFAULT_DOCS_DIR = PROJECT_ROOT / "docs"
 DEFAULT_PACKAGE_ROOT = "mail_intake"
 MKDOCS_YML = PROJECT_ROOT / "mkdocs.yml"
 
+
 def generate_docs_from_nav(
     project_root: Path,
     docs_root: Path,
@@ -52,11 +52,14 @@ def generate_docs_from_nav(
     - Walks the Python package structure
     - Mirrors it under the docs directory
     - Creates missing .md files
+    - Creates index.md for packages (__init__.py)
     - Overwrites content with ::: package.module
 
-    Example:
+    Examples:
-        mail_intake/config.py        -> docs/mail_intake/config.md
+        mail_intake/__init__.py           -> docs/mail_intake/index.md
-        mail_intake/adapters/base.py -> docs/mail_intake/adapters/base.md
+        mail_intake/config.py             -> docs/mail_intake/config.md
+        mail_intake/adapters/__init__.py  -> docs/mail_intake/adapters/index.md
+        mail_intake/adapters/base.py      -> docs/mail_intake/adapters/base.md
     """
 
     package_dir = project_root / package_root
@@ -66,17 +69,21 @@ def generate_docs_from_nav(
     docs_root.mkdir(parents=True, exist_ok=True)
 
     for py_file in package_dir.rglob("*.py"):
-        if py_file.name == "__init__.py":
-            continue
-
         rel = py_file.relative_to(project_root)
-        md_path = docs_root / rel.with_suffix(".md")
+
+        if py_file.name == "__init__.py":
+            # Package → index.md
+            module_path = ".".join(rel.parent.parts)
+            md_path = docs_root / rel.parent / "index.md"
+            title = rel.parent.name.replace("_", " ").title()
+        else:
+            # Regular module → <module>.md
+            module_path = ".".join(rel.with_suffix("").parts)
+            md_path = docs_root / rel.with_suffix(".md")
+            title = md_path.stem.replace("_", " ").title()
 
         md_path.parent.mkdir(parents=True, exist_ok=True)
 
-        module_path = ".".join(rel.with_suffix("").parts)
-        title = md_path.stem.replace("_", " ").title()
-
         content = f"""# {title}
 
 ::: {module_path}