rename mkdocs.py to mkdocs_renderer.py

docforge/renderers/mkdocs_renderer.py

@@ -0,0 +1,91 @@
+"""
+This module implements the MkDocsRenderer, which generates Markdown source files
+compatible with the MkDocs 'material' theme and 'mkdocstrings' extension.
+"""
+
+from pathlib import Path
+
+from docforge.models import Project
+
+
+class MkDocsRenderer:
+    """
+    Renderer that generates Markdown source files formatted for the MkDocs
+    'mkdocstrings' plugin.
+    """
+
+    name = "mkdocs"
+
+    def generate_sources(self, project: Project, out_dir: Path) -> None:
+        """
+        Produce a set of Markdown files in the output directory based on the
+        provided Project models.
+
+        Args:
+            project: The project models to render.
+            out_dir: Target directory for documentation files.
+        """
+        modules = list(project.get_all_modules())
+        paths = {m.path for m in modules}
+
+        # Package detection (level-agnostic)
+        packages = {
+            p for p in paths
+            if any(other.startswith(p + ".") for other in paths)
+        }
+
+        for module in modules:
+            self._write_module(module, packages, out_dir)
+
+    # -------------------------
+    # Internal helpers
+    # -------------------------
+    def _write_module(self, module, packages: set[str], out_dir: Path) -> None:
+        """
+        Write a single module's documentation file. Packages are written as
+        'index.md' inside their respective directories.
+
+        Args:
+            module: The module to write.
+            packages: A set of module paths that are identified as packages.
+            out_dir: The base output directory.
+        """
+        parts = module.path.split(".")
+
+        if module.path in packages:
+            # package → 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()
+        else:
+            # leaf module → <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()
+
+        content = self._render_markdown(title, module.path)
+
+        if md_path.exists() and md_path.read_text(encoding="utf-8") == content:
+            return
+
+        md_path.write_text(content, encoding="utf-8")
+
+    def _render_markdown(self, title: str, module_path: str) -> str:
+        """
+        Generate the Markdown content for a module file.
+
+        Args:
+            title: The display title for the page.
+            module_path: The dotted path of the module to document.
+
+        Returns:
+            A string containing the Markdown source.
+        """
+        return (
+            f"# {title}\n\n"
+            f"::: {module_path}\n"
+        )