added root index.md

docforge/renderers/mkdocs_renderer.py

@@ -1,10 +1,15 @@
 """
-This module implements the MkDocsRenderer, which generates Markdown source files
-compatible with the MkDocs 'material' theme and 'mkdocstrings' extension.
+MkDocsRenderer
+
+Generates Markdown source files compatible with MkDocs Material
+and mkdocstrings, ensuring:
+
+- Root index.md always exists
+- Parent package indexes are created automatically
+- Child modules are linked in parent index files
 """
 
 from pathlib import Path
-
 from docforge.models import Project
 
 
@@ -16,6 +21,9 @@ class MkDocsRenderer:
 
     name = "mkdocs"
 
+    # -------------------------
+    # Public API
+    # -------------------------
     def generate_sources(self, project: Project, out_dir: Path) -> None:
         """
         Produce a set of Markdown files in the output directory based on the
@@ -25,6 +33,9 @@ class MkDocsRenderer:
             project: The project models to render.
             out_dir: Target directory for documentation files.
         """
+        out_dir.mkdir(parents=True, exist_ok=True)
+        self._ensure_root_index(project, out_dir)
+
         modules = list(project.get_all_modules())
         paths = {m.path for m in modules}
 
@@ -53,26 +64,25 @@ class MkDocsRenderer:
         parts = module.path.split(".")
 
         if module.path in packages:
-            # package → index.md
+            # Package → directory/index.md
             dir_path = out_dir.joinpath(*parts)
             dir_path.mkdir(parents=True, exist_ok=True)
-
             md_path = dir_path / "index.md"
-            title = parts[-1].replace("_", " ").title()
+            link_target = f"{parts[-1]}/"
         else:
-            # leaf module → <name>.md
+            # Leaf module → parent_dir/<name>.md
             dir_path = out_dir.joinpath(*parts[:-1])
             dir_path.mkdir(parents=True, exist_ok=True)
-
             md_path = dir_path / f"{parts[-1]}.md"
-            title = parts[-1].replace("_", " ").title()
+            link_target = f"{parts[-1]}.md"
 
+        title = parts[-1].replace("_", " ").title()
         content = self._render_markdown(title, module.path)
 
-        if md_path.exists() and md_path.read_text(encoding="utf-8") == content:
-            return
+        if not md_path.exists() or md_path.read_text(encoding="utf-8") != content:
+            md_path.write_text(content, encoding="utf-8")
 
-        md_path.write_text(content, encoding="utf-8")
+        self._ensure_parent_index(parts, out_dir, link_target, title)
 
     def _render_markdown(self, title: str, module_path: str) -> str:
         """
@@ -89,3 +99,46 @@ class MkDocsRenderer:
             f"# {title}\n\n"
             f"::: {module_path}\n"
         )
+
+    def _ensure_root_index(
+        self,
+        project: Project,
+        out_dir: Path
+    ) -> None:
+        root_index = out_dir / "index.md"
+
+        if not root_index.exists():
+            root_index.write_text(
+                f"# {project.name}\n\n"
+                "## Modules\n\n",
+                encoding="utf-8",
+            )
+
+    def _ensure_parent_index(
+        self,
+        parts: list[str],
+        out_dir: Path,
+        link_target: str,
+        title: str,
+    ) -> None:
+        if len(parts) == 1:
+            parent_index = out_dir / "index.md"
+            link = f"- [{title}]({link_target})\n"
+        else:
+            parent_dir = out_dir.joinpath(*parts[:-1])
+            parent_dir.mkdir(parents=True, exist_ok=True)
+            parent_index = parent_dir / "index.md"
+
+            link = f"- [{title}]({link_target})\n"
+
+            if not parent_index.exists():
+                parent_title = parts[-2].replace("_", " ").title()
+                parent_index.write_text(
+                    f"# {parent_title}\n\n",
+                    encoding="utf-8",
+                )
+
+        content = parent_index.read_text(encoding="utf-8")
+
+        if link not in content:
+            parent_index.write_text(content + link, encoding="utf-8")