updated docs strings and added README.md

docforge/renderers/mkdocs_renderer.py

@@ -1,16 +1,18 @@
 """
+# Summary
+
 MkDocs renderer implementation.
 
-This module defines the ``MkDocsRenderer`` class, which generates Markdown
+This module defines the `MkDocsRenderer` class, which generates Markdown
 documentation sources compatible with MkDocs Material and the mkdocstrings
 plugin.
 
 The renderer ensures a consistent documentation structure by:
 
-- Creating a root ``index.md`` if one does not exist
+- Creating a root `index.md` if one does not exist
 - Generating package index pages automatically
 - Linking child modules within parent package pages
-- Optionally generating ``README.md`` from the root package docstring
+- Optionally generating `README.md` from the root package docstring
 """
 
 from pathlib import Path
@@ -45,10 +47,15 @@ class MkDocsRenderer:
         specified output directory.
 
         Args:
-            project: Project model containing modules to document.
-            out_dir: Directory where generated Markdown files will be written.
-            module_is_source: If True, treat the specified module as the
-                documentation root rather than nesting it inside a folder.
+            project (Project):
+                Project model containing modules to document.
+
+            out_dir (Path):
+                Directory where generated Markdown files will be written.
+
+            module_is_source (bool, optional):
+                If True, treat the specified module as the documentation root
+                rather than nesting it inside a folder.
         """
         out_dir.mkdir(parents=True, exist_ok=True)
         self._ensure_root_index(project, out_dir)
@@ -77,19 +84,23 @@ class MkDocsRenderer:
         module_is_source: bool | None = None,
     ) -> None:
         """
-        Generate a ``README.md`` file from the root module docstring.
+        Generate a `README.md` file from the root module docstring.
 
         Behavior:
 
-        - If ``module_is_source`` is True, ``README.md`` is written to the
-          project root directory.
+        - If `module_is_source` is True, `README.md` is written to the project
+          root directory.
         - If False, README generation is currently not implemented.
 
         Args:
-            project: Project model containing documentation metadata.
-            docs_dir: Directory containing generated documentation sources.
-            module_is_source: Whether the module is treated as the project
-                source root.
+            project (Project):
+                Project model containing documentation metadata.
+
+            docs_dir (Path):
+                Directory containing generated documentation sources.
+
+            module_is_source (bool, optional):
+                Whether the module is treated as the project source root.
         """
 
         if not module_is_source:
@@ -136,10 +147,12 @@ class MkDocsRenderer:
         Locate the root module corresponding to the project name.
 
         Args:
-            project: Project model to inspect.
+            project (Project):
+                Project model to inspect.
 
         Returns:
-            The root ``Module`` if found, otherwise ``None``.
+            Optional[Module]:
+                The root `Module` if found, otherwise `None`.
         """
         for module in project.get_all_modules():
             if module.path == project.name:
@@ -156,16 +169,22 @@ class MkDocsRenderer:
         """
         Write documentation for a single module.
 
-        Package modules are rendered as ``index.md`` files inside their
+        Package modules are rendered as `index.md` files inside their
         corresponding directories, while leaf modules are written as
         standalone Markdown pages.
 
         Args:
-            module: Module to render.
-            packages: Set of module paths identified as packages.
-            out_dir: Base directory for generated documentation files.
-            module_is_source: Whether the module acts as the documentation
-                root directory.
+            module (Module):
+                Module to render.
+
+            packages (set[str]):
+                Set of module paths identified as packages.
+
+            out_dir (Path):
+                Base directory for generated documentation files.
+
+            module_is_source (bool, optional):
+                Whether the module acts as the documentation root directory.
         """
 
         parts = module.path.split(".")
@@ -202,11 +221,15 @@ class MkDocsRenderer:
         Generate Markdown content for a module documentation page.
 
         Args:
-            title: Page title displayed in the documentation.
-            module_path: Dotted import path of the module.
+            title (str):
+                Page title displayed in the documentation.
+
+            module_path (str):
+                Dotted import path of the module.
 
         Returns:
-            Markdown source containing a mkdocstrings directive.
+            str:
+                Markdown source containing a mkdocstrings directive.
         """
         return (
             f"# {title}\n\n"
@@ -219,11 +242,14 @@ class MkDocsRenderer:
         out_dir: Path,
     ) -> None:
         """
-        Ensure that the root ``index.md`` page exists.
+        Ensure that the root `index.md` page exists.
 
         Args:
-            project: Project model used for the page title.
-            out_dir: Documentation output directory.
+            project (Project):
+                Project model used for the page title.
+
+            out_dir (Path):
+                Documentation output directory.
         """
         root_index = out_dir / "index.md"
 
@@ -246,10 +272,17 @@ class MkDocsRenderer:
         child modules.
 
         Args:
-            parts: Module path components.
-            out_dir: Documentation output directory.
-            link_target: Link target used in the parent index.
-            title: Display title for the link.
+            parts (list[str]):
+                Module path components.
+
+            out_dir (Path):
+                Documentation output directory.
+
+            link_target (str):
+                Link target used in the parent index.
+
+            title (str):
+                Display title for the link.
         """
         if len(parts) == 1:
             parent_index = out_dir / "index.md"