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/commands.py

@@ -9,8 +9,10 @@ from docforge.cli import mcp_utils
 @click.group()
 def cli() -> None:
     """
-    doc-forge CLI: A tool for introspecting Python projects and generating
-    documentation.
+    Root command group for the doc-forge CLI.
+
+    Provides commands for building, serving, and inspecting
+    documentation generated from Python source code.
     """
     pass
 
@@ -21,14 +23,12 @@ def cli() -> None:
 @click.option("--module-is-source", is_flag=True, help="Module is source folder and to be treated as root folder")
 @click.option("--module", help="Python module to document")
 @click.option("--project-name", help="Project name override")
-# MkDocs specific
 @click.option("--site-name", help="MkDocs site name")
 @click.option("--docs-dir", type=click.Path(path_type=Path), default=Path("docs"), help="Directory for MD sources")
 @click.option("--nav", "nav_file", type=click.Path(path_type=Path), default=Path("docforge.nav.yml"),
               help="Nav spec path")
 @click.option("--template", type=click.Path(path_type=Path), help="MkDocs template path")
 @click.option("--mkdocs-yml", type=click.Path(path_type=Path), default=Path("mkdocs.yml"), help="Output config path")
-# MCP specific
 @click.option("--out-dir", type=click.Path(path_type=Path), default=Path("mcp_docs"), help="MCP output directory")
 def build(
     mcp: bool,
@@ -44,25 +44,36 @@ def build(
     out_dir: Path,
 ) -> None:
     """
-    Build documentation (MkDocs site or MCP resources).
+    Build documentation artifacts.
 
-    This command orchestrates the full build process:
-    1. Introspects the code (Griffe)
-    2. Renders sources (MkDocs Markdown or MCP JSON)
-    3. (MkDocs only) Generates config and runs the final site build.
+    This command performs the full documentation build pipeline:
+
+    1. Introspects the Python project using Griffe
+    2. Generates renderer-specific documentation sources
+    3. Optionally builds the final documentation output
+
+    Depending on the selected options, the build can target:
+
+    - MkDocs static documentation sites
+    - MCP structured documentation resources
 
     Args:
-        mcp: Use the MCP documentation builder.
-        mkdocs: Use the MkDocs documentation builder.
-        module_is_source: Module is the source folder and to be treated as the root folder.
-        module: The dotted path of the module to the document.
+        mcp: Enable MCP documentation generation.
+        mkdocs: Enable MkDocs documentation generation.
+        module_is_source: Treat the specified module directory as the
+            project root.
+        module: Python module import path to document.
         project_name: Optional override for the project name.
-        site_name: (MkDocs) The site display name. Defaults to module name.
-        docs_dir: (MkDocs) Target directory for Markdown sources.
-        nav_file: (MkDocs) Path to the docforge.nav.yml specification.
-        template: (MkDocs) Optional custom mkdocs.yml template.
-        mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.
-        out_dir: (MCP) Target directory for MCP JSON resources.
+        site_name: Display name for the MkDocs site.
+        docs_dir: Directory where Markdown documentation sources
+            will be generated.
+        nav_file: Path to the navigation specification file.
+        template: Optional custom MkDocs configuration template.
+        mkdocs_yml: Output path for the generated MkDocs configuration.
+        out_dir: Output directory for generated MCP resources.
+
+    Raises:
+        click.UsageError: If required options are missing or conflicting.
     """
     if not mcp and not mkdocs:
         raise click.UsageError("Must specify either --mcp or --mkdocs")
@@ -111,14 +122,22 @@ def serve(
     out_dir: Path,
 ) -> None:
     """
-    Serve documentation (MkDocs or MCP).
+    Serve generated documentation locally.
+
+    Depending on the selected mode, this command starts either:
+
+    - A MkDocs development server for browsing documentation
+    - An MCP server exposing structured documentation resources
 
     Args:
-        mcp: Serve MCP resources via an MCP server.
-        mkdocs: Serve the MkDocs site using the built-in development server.
-        module: The dotted path of the module to serve.
-        mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.
-        out_dir: (MCP) Path to the mcp_docs/ directory.
+        mcp: Serve documentation using the MCP server.
+        mkdocs: Serve the MkDocs development site.
+        module: Python module import path to serve via MCP.
+        mkdocs_yml: Path to the MkDocs configuration file.
+        out_dir: Root directory containing MCP documentation resources.
+
+    Raises:
+        click.UsageError: If invalid or conflicting options are provided.
     """
     if mcp and mkdocs:
         raise click.UsageError("Cannot specify both --mcp and --mkdocs")
@@ -148,11 +167,15 @@ def tree(
     project_name: Optional[str],
 ) -> None:
     """
-    Visualize the project structure in the terminal.
+    Display the documentation object tree for a module.
+
+    This command introspects the specified module and prints a
+    hierarchical representation of the discovered documentation
+    objects, including modules, classes, functions, and members.
 
     Args:
-        module: The module import path to recursively introspect.
-        project_name: Optional override for the project name shown at the root.
+        module: Python module import path to introspect.
+        project_name: Optional name to display as the project root.
     """
     loader = GriffeLoader()
     project = loader.load_project([module], project_name)
@@ -167,11 +190,14 @@ def tree(
 
 def _print_object(obj, indent: str) -> None:
     """
-    Recursive helper to print doc objects and their members to the console.
+    Recursively print a documentation object and its members.
+
+    This helper function traverses the documentation object graph
+    and prints each object with indentation to represent hierarchy.
 
     Args:
-        obj: The DocObject instance to print.
-        indent: Current line indentation (e.g., '│   ').
+        obj: Documentation object to print.
+        indent: Current indentation prefix used for nested members.
     """
     click.echo(f"{indent}├── {obj.name}")
     for member in obj.get_all_members():