updated docs strings and added README.md

docforge/cli/mkdocs_utils.py

@@ -1,3 +1,9 @@
+"""
+# Summary
+
+Utilities for working with MkDocs in the doc-forge CLI.
+"""
+
 from pathlib import Path
 from importlib import resources
 import click
@@ -21,13 +27,19 @@ def generate_sources(
     use with MkDocs.
 
     Args:
-        module: Python module import path used as the entry point for
+        module (str):
+            Python module import path used as the entry point for
             documentation generation.
-        docs_dir: Directory where the generated Markdown files will be written.
-        project_name: Optional override for the project name used in
-            documentation metadata.
-        module_is_source: If True, treat the specified module directory as
-            the project root rather than a nested module.
+
+        docs_dir (Path):
+            Directory where the generated Markdown files will be written.
+
+        project_name (Optional[str]):
+            Optional override for the project name used in documentation metadata.
+
+        module_is_source (Optional[bool]):
+            If True, treat the specified module directory as the project root
+            rather than a nested module.
     """
     loader = GriffeLoader()
     discovered_paths = discover_module_paths(module)
@@ -55,24 +67,32 @@ def generate_config(
     site_name: str,
 ) -> None:
     """
-    Generate an ``mkdocs.yml`` configuration file.
+    Generate an `mkdocs.yml` configuration file.
 
     The configuration is created by combining a template configuration
     with a navigation structure derived from the docforge navigation
     specification.
 
     Args:
-        docs_dir: Directory containing generated documentation Markdown files.
-        nav_file: Path to the ``docforge.nav.yml`` navigation specification.
-        template: Optional path to a custom MkDocs configuration template.
-            If not provided, a built-in template will be used.
-        out: Destination path where the generated ``mkdocs.yml`` file
-            will be written.
-        site_name: Display name for the generated documentation site.
+        docs_dir (Path):
+            Directory containing generated documentation Markdown files.
+
+        nav_file (Path):
+            Path to the `docforge.nav.yml` navigation specification.
+
+        template (Optional[Path]):
+            Optional path to a custom MkDocs configuration template. If not
+            provided, a built-in template will be used.
+
+        out (Path):
+            Destination path where the generated `mkdocs.yml` file will be written.
+
+        site_name (str):
+            Display name for the generated documentation site.
 
     Raises:
-        click.FileError: If the navigation specification or template
-            file cannot be found.
+        click.FileError:
+            If the navigation specification or template file cannot be found.
     """
     if not nav_file.exists():
         raise click.FileError(str(nav_file), hint="Nav spec not found")
@@ -108,10 +128,12 @@ def build(mkdocs_yml: Path) -> None:
     build command to generate the final static documentation site.
 
     Args:
-        mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.
+        mkdocs_yml (Path):
+            Path to the `mkdocs.yml` configuration file.
 
     Raises:
-        click.ClickException: If the configuration file does not exist.
+        click.ClickException:
+            If the configuration file does not exist.
     """
     if not mkdocs_yml.exists():
         raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
@@ -130,10 +152,12 @@ def serve(mkdocs_yml: Path) -> None:
     the site when changes are detected.
 
     Args:
-        mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.
+        mkdocs_yml (Path):
+            Path to the `mkdocs.yml` configuration file.
 
     Raises:
-        click.ClickException: If the configuration file does not exist.
+        click.ClickException:
+            If the configuration file does not exist.
     """
     if not mkdocs_yml.exists():
         raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")