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

@@ -1,14 +1,31 @@
 """
-# CLI Layer
+Command line interface entry point for doc-forge.
 
-The `docforge.cli` package provides the command-line interface for interacting
-with doc-forge.
+This module exposes the primary CLI entry function used by the
+``doc-forge`` command. The actual command implementation resides in
+``docforge.cli.main``, while this module provides a stable import path
+for external tools and the package entry point configuration.
 
-## Available Commands
+The CLI is responsible for orchestrating documentation workflows such as
+generating renderer sources, building documentation sites, exporting
+machine-readable documentation bundles, and starting development or MCP
+servers.
 
-- **build**: Build documentation (MkDocs site or MCP resources).
-- **serve**: Serve documentation (MkDocs or MCP).
-- **tree**: Visualize the introspected project structure.
+---
+
+Typical usage
+-------------
+
+The CLI is normally invoked through the installed command:
+
+    doc-forge <command> [options]
+
+Programmatic invocation is also possible:
+
+    from docforge.cli import main
+    main()
+
+---
 """
 
 from .main import main

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():

docforge/cli/main.py

@@ -1,14 +1,23 @@
 """
-Main entry point for the doc-forge CLI. This module delegates all command
-execution to docforge.cli.commands.
+Command-line entry point for the doc-forge CLI.
+
+This module exposes the executable entry point that initializes the
+Click command group defined in ``docforge.cli.commands``.
 """
+
 from docforge.cli.commands import cli
 
+
 def main() -> None:
     """
-    CLI Entry point. Boots the click application.
+    Run the doc-forge command-line interface.
+
+    This function initializes and executes the Click CLI application.
+    It is used as the console entry point when invoking ``doc-forge``
+    from the command line.
     """
     cli()
 
+
 if __name__ == "__main__":
-    main()
+    main()

docforge/cli/mcp_utils.py

@@ -4,14 +4,22 @@ from docforge.loaders import GriffeLoader, discover_module_paths
 from docforge.renderers import MCPRenderer
 from docforge.servers import MCPServer
 
+
 def generate_resources(module: str, project_name: str | None, out_dir: Path) -> None:
     """
-    Generate MCP-compatible documentation resources.
+    Generate MCP documentation resources from a Python module.
+
+    The function performs project introspection, builds the internal
+    documentation model, and renders MCP-compatible JSON resources
+    to the specified output directory.
 
     Args:
-        module: The dotted path of the primary module to document.
-        project_name: Optional override for the project name.
-        out_dir: Directory where the MCP JSON resources and nav will be written.
+        module: Python module import path used as the entry point for
+            documentation generation.
+        project_name: Optional override for the project name used in
+            generated documentation metadata.
+        out_dir: Directory where MCP resources (index.json, nav.json,
+            and module data) will be written.
     """
     loader = GriffeLoader()
     discovered_paths = discover_module_paths(module)
@@ -20,13 +28,23 @@ def generate_resources(module: str, project_name: str | None, out_dir: Path) ->
     renderer = MCPRenderer()
     renderer.generate_sources(project, out_dir)
 
+
 def serve(module: str, mcp_root: Path) -> None:
     """
-    Serve MCP documentation from a pre-built bundle.
+    Start an MCP server for a pre-generated documentation bundle.
+
+    The server exposes documentation resources such as project metadata,
+    navigation structure, and module documentation through MCP endpoints.
 
     Args:
-        module: The dotted path of the primary module to serve.
-        mcp_root: Path to the directory containing index.json, nav.json, and modules/.
+        module: Python module import path used to identify the served
+            documentation instance.
+        mcp_root: Path to the directory containing the MCP documentation
+            bundle (index.json, nav.json, and modules/).
+
+    Raises:
+        click.ClickException: If the MCP documentation bundle is missing
+            required files or directories.
     """
     if not mcp_root.exists():
         raise click.ClickException(f"mcp_docs directory not found: {mcp_root}")

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}")