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>

mcp_docs/modules/docforge.nav.mkdocs.json

@@ -2,7 +2,7 @@
   "module": "docforge.nav.mkdocs",
   "content": {
     "path": "docforge.nav.mkdocs",
-    "docstring": "This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance\ninto the specific YAML-ready list structure expected by the MkDocs 'nav'\nconfiguration.",
+    "docstring": "MkDocs navigation emitter.\n\nThis module provides the ``MkDocsNavEmitter`` class, which converts a\n``ResolvedNav`` instance into the navigation structure required by the\nMkDocs ``nav`` configuration.",
     "objects": {
       "Path": {
         "name": "Path",
@@ -37,7 +37,7 @@
         "kind": "class",
         "path": "docforge.nav.mkdocs.ResolvedNav",
         "signature": "<bound method Alias.signature of Alias('ResolvedNav', 'docforge.nav.resolver.ResolvedNav')>",
-        "docstring": "Represents a navigation structure where all patterns and paths have been\nresolved against the actual filesystem contents.\n\nAttributes:\n    home: Resolved relative path to the home page.\n    groups: Mapping of group titles to lists of absolute or relative Path objects.",
+        "docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n    home: Relative path to the documentation home page.\n    groups: Mapping of navigation group titles to lists of resolved\n        documentation file paths.",
         "members": {
           "home": {
             "name": "home",
@@ -58,7 +58,7 @@
             "kind": "function",
             "path": "docforge.nav.mkdocs.ResolvedNav.all_files",
             "signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>",
-            "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n    An iterable of Path objects."
+            "docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n    An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n    RuntimeError: If the home page is defined but the documentation\n        root is not available for resolution."
           }
         }
       },
@@ -66,15 +66,15 @@
         "name": "MkDocsNavEmitter",
         "kind": "class",
         "path": "docforge.nav.mkdocs.MkDocsNavEmitter",
-        "signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 13, 72)>",
-        "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
+        "signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 15, 81)>",
+        "docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.",
         "members": {
           "emit": {
             "name": "emit",
             "kind": "function",
             "path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit",
-            "signature": "<bound method Function.signature of Function('emit', 19, 44)>",
-            "docstring": "Generate a list of navigation entries for mkdocs.yml.\n\nArgs:\n    nav: The resolved navigation data.\n\nReturns:\n    A list of dictionary mappings representing the MkDocs navigation."
+            "signature": "<bound method Function.signature of Function('emit', 23, 51)>",
+            "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n    nav: Resolved navigation data describing documentation groups\n        and their associated Markdown files.\n\nReturns:\n    A list of dictionaries representing the MkDocs navigation layout.\n    Each dictionary maps a navigation label to a page or a list of\n    pages."
           }
         }
       }