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/models/object.py

@@ -1,7 +1,10 @@
 """
-This module defines the DocObject class, the fundamental recursive unit of the
-doc-forge documentation models. A DocObject represents a single Python entity
-(class, function, method, or attribute) and its nested members.
+Documentation model representing individual Python objects.
+
+This module defines the ``DocObject`` class, the fundamental recursive unit of
+the doc-forge documentation model. Each ``DocObject`` represents a Python
+entity such as a class, function, method, or attribute, and may contain nested
+members that form a hierarchical documentation structure.
 """
 
 from typing import Dict, Iterable, Optional
@@ -9,15 +12,20 @@ from typing import Dict, Iterable, Optional
 
 class DocObject:
     """
-    Represents a documented Python object (class, function, method, etc.).
+    Representation of a documented Python object.
+
+    A ``DocObject`` models a single Python entity discovered during
+    introspection. Objects may contain nested members, allowing the structure
+    of modules, classes, and other containers to be represented recursively.
 
     Attributes:
         name: Local name of the object.
-        kind: Type of object (e.g., 'class', 'function', 'attribute').
-        path: Full dotted import path to the object.
-        signature: Callable signature, if applicable.
-        docstring: Raw docstring content extracted from the source.
-        members: Dictionary mapping member names to their DocObject representations.
+        kind: Type of object (for example ``class``, ``function``,
+            ``method``, or ``attribute``).
+        path: Fully qualified dotted path to the object.
+        signature: Callable signature if the object represents a callable.
+        docstring: Raw docstring text extracted from the source code.
+        members: Mapping of member names to child ``DocObject`` instances.
     """
 
     def __init__(
@@ -29,48 +37,54 @@ class DocObject:
         docstring: Optional[str] = None,
     ) -> None:
         """
-        Initialize a new DocObject.
+        Initialize a DocObject instance.
 
         Args:
-            name: The local name of the object.
-            kind: The kind of object (e.g., 'class', 'function').
-            path: The full dotted path to the object.
-            signature: The object's signature (for callable objects).
-            docstring: The object's docstring, if any.
+            name: Local name of the object.
+            kind: Object type identifier (for example ``class`` or ``function``).
+            path: Fully qualified dotted path of the object.
+            signature: Callable signature if applicable.
+            docstring: Documentation string associated with the object.
         """
         self.name = name
         self.kind = kind
         self.path = path
         self.signature = signature
         self.docstring = docstring
-        self.members: Dict[str, 'DocObject'] = {}
+        self.members: Dict[str, "DocObject"] = {}
 
-    def add_member(self, obj: 'DocObject') -> None:
+    def add_member(self, obj: "DocObject") -> None:
         """
-        Add a child member to this object (e.g., a method to a class).
+        Add a child documentation object.
+
+        This is typically used when attaching methods to classes or
+        nested objects to their parent containers.
 
         Args:
-            obj: The child DocObject to add.
+            obj: Documentation object to add as a member.
         """
         self.members[obj.name] = obj
 
-    def get_member(self, name: str) -> 'DocObject':
+    def get_member(self, name: str) -> "DocObject":
         """
-        Retrieve a child member by name.
+        Retrieve a member object by name.
 
         Args:
-            name: The name of the member.
+            name: Name of the member to retrieve.
 
         Returns:
-            The requested DocObject.
+            The corresponding ``DocObject`` instance.
+
+        Raises:
+            KeyError: If the member does not exist.
         """
         return self.members[name]
 
-    def get_all_members(self) -> Iterable['DocObject']:
+    def get_all_members(self) -> Iterable["DocObject"]:
         """
-        Get all members of this object.
+        Return all child members of the object.
 
         Returns:
-            An iterable of child DocObject instances.
+            An iterable of ``DocObject`` instances representing nested members.
         """
         return self.members.values()