module is source flag to ensure for single source modules it's not treated as a module but root

docforge/renderers/mkdocs_renderer.py

@@ -10,7 +10,7 @@ and mkdocstrings, ensuring:
 """
 
 from pathlib import Path
-from docforge.models import Project
+from docforge.models import Project, Module
 
 
 class MkDocsRenderer:
@@ -24,7 +24,12 @@ class MkDocsRenderer:
     # -------------------------
     # Public API
     # -------------------------
-    def generate_sources(self, project: Project, out_dir: Path) -> None:
+    def generate_sources(
+        self,
+        project: Project,
+        out_dir: Path,
+        module_is_source: bool | None = None,
+    ) -> None:
         """
         Produce a set of Markdown files in the output directory based on the
         provided Project models.
@@ -32,6 +37,7 @@ class MkDocsRenderer:
         Args:
             project: The project models to render.
             out_dir: Target directory for documentation files.
+            module_is_source: Module is the source folder and to be treated as the root folder.
         """
         out_dir.mkdir(parents=True, exist_ok=True)
         self._ensure_root_index(project, out_dir)
@@ -46,12 +52,23 @@ class MkDocsRenderer:
         }
 
         for module in modules:
-            self._write_module(module, packages, out_dir)
+            self._write_module(
+                module,
+                packages,
+                out_dir,
+                module_is_source,
+            )
 
     # -------------------------
     # Internal helpers
     # -------------------------
-    def _write_module(self, module, packages: set[str], out_dir: Path) -> None:
+    def _write_module(
+        self,
+        module: Module,
+        packages: set[str],
+        out_dir: Path,
+        module_is_source: bool | None = None,
+    ) -> None:
         """
         Write a single module's documentation file. Packages are written as
         'index.md' inside their respective directories.
@@ -60,29 +77,36 @@ class MkDocsRenderer:
             module: The module to write.
             packages: A set of module paths that are identified as packages.
             out_dir: The base output directory.
+            module_is_source: Module is the source folder and to be treated as the root folder.
         """
         parts = module.path.split(".")
 
+        if module_is_source:
+            module_name, parts = parts[0], parts[1:]
+        else:
+            module_name, parts = parts[0], parts
+
         if module.path in packages:
             # Package → directory/index.md
             dir_path = out_dir.joinpath(*parts)
             dir_path.mkdir(parents=True, exist_ok=True)
             md_path = dir_path / "index.md"
-            link_target = f"{parts[-1]}/"
+            link_target = f"{parts[-1]}/" if parts else None
         else:
             # 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"
-            link_target = f"{parts[-1]}.md"
+            link_target = f"{parts[-1]}.md" if parts else None
 
-        title = parts[-1].replace("_", " ").title()
+        title = parts[-1].replace("_", " ").title() if parts else module_name
         content = self._render_markdown(title, module.path)
 
         if not md_path.exists() or md_path.read_text(encoding="utf-8") != content:
             md_path.write_text(content, encoding="utf-8")
 
-        self._ensure_parent_index(parts, out_dir, link_target, title)
+        if not module_is_source:
+            self._ensure_parent_index(parts, out_dir, link_target, title)
 
     def _render_markdown(self, title: str, module_path: str) -> str:
         """

docforge/renderers/mkdocs_renderer.pyi

@@ -1,19 +1,23 @@
 from pathlib import Path
-from typing import Set
-
 from docforge.models import Project, Module
 
 
 class MkDocsRenderer:
     name: str
 
-    def generate_sources(self, project: Project, out_dir: Path) -> None: ...
+    def generate_sources(
+        self,
+        project: Project,
+        out_dir: Path,
+        module_is_source: bool | None = None,
+    ) -> None: ...
 
     def _write_module(
         self,
         module: Module,
-        packages: Set[str],
+        packages: set[str],
         out_dir: Path,
+        module_is_source: bool | None = None,
     ) -> None: ...
 
     def _render_markdown(self, title: str, module_path: str) -> str: ...