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/nav/mkdocs.py

@@ -1,7 +1,9 @@
 """
-This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance
-into the specific YAML-ready list structure expected by the MkDocs 'nav'
-configuration.
+MkDocs navigation emitter.
+
+This module provides the ``MkDocsNavEmitter`` class, which converts a
+``ResolvedNav`` instance into the navigation structure required by the
+MkDocs ``nav`` configuration.
 """
 
 from pathlib import Path
@@ -12,19 +14,24 @@ from docforge.nav.resolver import ResolvedNav
 
 class MkDocsNavEmitter:
     """
-    Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible
-    navigation structure.
+    Emit MkDocs navigation structures from resolved navigation data.
+
+    The emitter transforms a ``ResolvedNav`` object into the YAML-compatible
+    list structure expected by the MkDocs ``nav`` configuration field.
     """
 
     def emit(self, nav: ResolvedNav) -> List[Dict[str, Any]]:
         """
-        Generate a list of navigation entries for mkdocs.yml.
+        Generate a navigation structure for ``mkdocs.yml``.
 
         Args:
-            nav: The resolved navigation data.
+            nav: Resolved navigation data describing documentation groups
+                and their associated Markdown files.
 
         Returns:
-            A list of dictionary mappings representing the MkDocs navigation.
+            A list of dictionaries representing the MkDocs navigation layout.
+            Each dictionary maps a navigation label to a page or a list of
+            pages.
         """
         result: List[Dict[str, Any]] = []
 
@@ -45,16 +52,18 @@ class MkDocsNavEmitter:
 
     def _to_relative(self, path: Path, docs_root: Path | None) -> str:
         """
-        Convert a filesystem path to a path relative to the documentation root.
-        This handles both absolute and relative filesystem paths, ensuring the
-        output is compatible with MkDocs navigation requirements.
+        Convert a filesystem path into a documentation-relative path.
+
+        This method normalizes paths so they can be used in MkDocs navigation.
+        It handles both absolute and relative filesystem paths and ensures the
+        resulting path is relative to the documentation root.
 
         Args:
-            path: The path to convert.
-            docs_root: The root directory for documentation.
+            path: Filesystem path to convert.
+            docs_root: Root directory of the documentation sources.
 
         Returns:
-            A string representing the relative POSIX-style path.
+            POSIX-style path relative to the documentation root.
         """
         if docs_root and path.is_absolute():
             try:
@@ -67,6 +76,6 @@ class MkDocsNavEmitter:
             docs_root_str = docs_root.as_posix()
             if path_str.startswith(docs_root_str + "/"):
                 return path_str[len(docs_root_str) + 1:]
-        
+
         # Fallback for other cases
         return path.as_posix().split("/docs/", 1)[-1]