Improve documentation look & feel via MkDocs Material template enhancements (#5)

# Improve documentation look & feel via MkDocs Material template enhancements

## Summary

This MR improves the overall **documentation experience and visual presentation** of the doc-forge docs by enhancing the MkDocs Material template configuration.

The changes focus on **navigation usability, code readability, and richer Markdown rendering**, resulting in a cleaner and more professional documentation site.

Docstring changes were made across the codebase for consistency, but this MR description focuses on the **template and presentation improvements**.

---

## Navigation Improvements

The navigation system has been enhanced to provide a clearer structure and better discoverability.

Key improvements include:

* Section-aware navigation in the sidebar
* Automatic expansion of module/package hierarchy
* Scroll tracking within the sidebar
* Clickable package index pages

Material navigation features added:

* `navigation.sections`
* `navigation.expand`
* `navigation.tracking`
* `navigation.indexes`

This results in a **single cohesive navigation tree** that exposes the entire documentation hierarchy from the sidebar.

---

## Code Block Improvements

Code blocks previously appeared relatively plain. The template now enables richer syntax highlighting and improved readability.

Enhancements include:

* Syntax highlighting using `pymdownx.highlight`
* Line numbers for code blocks
* Anchored line numbers for deep linking
* Improved fenced code block rendering

Additional Material features:

* `content.code.copy` — copy button for code blocks
* `content.code.annotate` — support for code annotations

These changes significantly improve the readability of examples and API snippets throughout the documentation.

---

## Markdown Rendering Enhancements

Additional Markdown extensions were enabled to support richer documentation features:

* `pymdownx.superfences` for advanced fenced blocks
* `pymdownx.inlinehilite` for inline code highlighting
* `pymdownx.snippets` for reusable snippets
* `admonition` and `pymdownx.details` for callouts and collapsible sections
* `pymdownx.tabbed` for tabbed content blocks
* `pymdownx.tasklist` for checklist-style items
* `tables`, `footnotes`, and advanced formatting extensions

These extensions make it easier to write expressive and structured documentation.

---

## Search Experience

The documentation search experience has been improved using Material search features:

* `search.highlight`
* `search.share`
* `search.suggest`

These enhancements provide:

* highlighted search matches
* sharable search URLs
* auto-suggestions while typing

---

## mkdocstrings Improvements

The mkdocstrings configuration has been expanded to produce clearer API documentation.

Notable improvements include:

* grouping objects by category
* explicit category headings
* improved symbol headings
* cleaner object path display

This results in more structured API documentation pages.

---

## Result

Overall, these changes provide:

* cleaner and more intuitive navigation
* significantly improved code presentation
* richer Markdown capabilities
* better search usability

The documentation now has a **more polished, modern appearance** and improved usability for both readers and contributors.

Reviewed-on: #5
Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>

docforge/cli/mkdocs_utils.py

@@ -6,6 +6,7 @@ from docforge.loaders import GriffeLoader, discover_module_paths
 from docforge.renderers import MkDocsRenderer
 from docforge.nav import load_nav_spec, resolve_nav, MkDocsNavEmitter
 
+
 def generate_sources(
     module: str,
     docs_dir: Path,
@@ -13,13 +14,20 @@ def generate_sources(
     module_is_source: bool | None = None,
 ) -> None:
     """
-    Generate Markdown source files for the specified module.
+    Generate MkDocs Markdown sources for a Python module.
+
+    This function introspects the specified module, builds the internal
+    documentation model, and renders Markdown documentation files for
+    use with MkDocs.
 
     Args:
-        module: The dotted path of the primary module to document.
-        project_name: Optional override for the project name.
+        module: Python module import path used as the entry point for
+            documentation generation.
         docs_dir: Directory where the generated Markdown files will be written.
-        module_is_source: Module is the source folder and to be treated as the root folder.
+        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.
     """
     loader = GriffeLoader()
     discovered_paths = discover_module_paths(module)
@@ -32,16 +40,39 @@ def generate_sources(
         module_is_source,
     )
 
-def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None:
+    renderer.generate_readme(
+        project,
+        docs_dir,
+        module_is_source,
+    )
+
+
+def generate_config(
+    docs_dir: Path,
+    nav_file: Path,
+    template: Path | None,
+    out: Path,
+    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: Path to the directory containing documentation Markdown files.
-        nav_file: Path to the docforge.nav.yml specification.
-        template: Optional path to an mkdocs.yml template (overrides built-in).
-        out: Path where the final mkdocs.yml will be written.
-        site_name: The display name for the documentation site.
+        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.
+
+    Raises:
+        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")
@@ -68,12 +99,19 @@ def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out:
 
     out.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
 
+
 def build(mkdocs_yml: Path) -> None:
     """
-    Build the documentation site using MkDocs.
+    Build the MkDocs documentation site.
+
+    This function loads the MkDocs configuration and runs the MkDocs
+    build command to generate the final static documentation site.
 
     Args:
-        mkdocs_yml: Path to the mkdocs.yml configuration file.
+        mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.
+
+    Raises:
+        click.ClickException: If the configuration file does not exist.
     """
     if not mkdocs_yml.exists():
         raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
@@ -83,12 +121,19 @@ def build(mkdocs_yml: Path) -> None:
 
     mkdocs_build(load_config(str(mkdocs_yml)))
 
+
 def serve(mkdocs_yml: Path) -> None:
     """
-    Serve the documentation site with live-reload using MkDocs.
+    Start an MkDocs development server with live reload.
+
+    The server watches documentation files and automatically reloads
+    the site when changes are detected.
 
     Args:
-        mkdocs_yml: Path to the mkdocs.yml configuration file.
+        mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.
+
+    Raises:
+        click.ClickException: If the configuration file does not exist.
     """
     if not mkdocs_yml.exists():
         raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")