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

@@ -1,7 +1,9 @@
 """
-This module defines the NavSpec class, which represents the user's intent for
-documentation navigation as defined in a YAML specification (usually
-docforge.nav.yml).
+Navigation specification model.
+
+This module defines the ``NavSpec`` class, which represents the navigation
+structure defined by the user in the doc-forge navigation specification
+(typically ``docforge.nav.yml``).
 """
 
 from pathlib import Path
@@ -12,11 +14,16 @@ import yaml
 
 class NavSpec:
     """
-    Parsed representation of the docforge navigation specification file.
+    Parsed representation of a navigation specification.
+
+    A ``NavSpec`` describes the intended documentation navigation layout before
+    it is resolved against the filesystem.
 
     Attributes:
-        home: Path to the home document (e.g., 'index.md').
-        groups: Mapping of group titles to lists of path patterns/globs.
+        home: Relative path to the documentation home page (for example
+            ``index.md``).
+        groups: Mapping of navigation group titles to lists of file patterns
+            or glob expressions.
     """
 
     def __init__(
@@ -25,11 +32,12 @@ class NavSpec:
         groups: Dict[str, List[str]],
     ) -> None:
         """
-        Initialize a NavSpec.
+        Initialize a NavSpec instance.
 
         Args:
-            home: The path to the home document.
-            groups: A mapping of group names to lists of path patterns (globs).
+            home: Relative path to the home document.
+            groups: Mapping of group names to lists of path patterns
+                (glob expressions).
         """
         self.home = home
         self.groups = groups
@@ -37,17 +45,18 @@ class NavSpec:
     @classmethod
     def load(cls, path: Path) -> "NavSpec":
         """
-        Load a NavSpec from a YAML file.
+        Load a navigation specification from a YAML file.
 
         Args:
-            path: The filesystem path to the YAML file.
+            path: Filesystem path to the navigation specification file.
 
         Returns:
-            A NavSpec instance.
+            A ``NavSpec`` instance representing the parsed configuration.
 
         Raises:
-            FileNotFoundError: If the path does not exist.
-            ValueError: If the file content is not a valid NavSpec mapping.
+            FileNotFoundError: If the specified file does not exist.
+            ValueError: If the file contents are not a valid navigation
+                specification.
         """
         if not path.exists():
             raise FileNotFoundError(path)
@@ -78,33 +87,45 @@ class NavSpec:
 
     def all_patterns(self) -> List[str]:
         """
-        Get all path patterns referenced in the specification.
+        Return all path patterns referenced by the specification.
 
         Returns:
-            A list of all patterns (home plus all groups).
+            A list containing the home document (if defined) and all
+            group pattern entries.
         """
         patterns: List[str] = []
+
         if self.home:
             patterns.append(self.home)
+
         for items in self.groups.values():
             patterns.extend(items)
+
         return patterns
 
 
 def load_nav_spec(path: Path) -> NavSpec:
     """
-    Utility function to load a NavSpec from a file.
+    Load a navigation specification file.
+
+    This helper function reads a YAML navigation file and constructs a
+    corresponding ``NavSpec`` instance.
 
     Args:
         path: Path to the navigation specification file.
 
     Returns:
-        A loaded NavSpec instance.
+        A ``NavSpec`` instance representing the parsed specification.
+
+    Raises:
+        FileNotFoundError: If the specification file does not exist.
+        ValueError: If the YAML structure is invalid.
     """
     if not path.exists():
         raise FileNotFoundError(path)
 
     data = yaml.safe_load(path.read_text(encoding="utf-8"))
+
     if not isinstance(data, dict):
         raise ValueError("Nav spec must be a YAML mapping")