aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve documentation look & feel via MkDocs Material template enhancements (#5)

Browse Source 
# 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>
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-03-07 10:50:18 +00:00
committed by aetos
parent f8ca6075fb
commit b6306baafc
51 changed files with 2222 additions and 1239 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
docforge/models/__init__.py
View File

@@ -1,17 +1,32 @@
"""
# Model Layer
Model layer for doc-forge.
The `docforge.models` package provides the core data structures used to represent
Python source code in a documentation-focused hierarchy.
The ``docforge.models`` package defines the core data structures used to
represent Python source code as a structured documentation model.
## Key Components
---
- **Project**: The root container for all documented modules.
- **Module**: Represents a Python module or package, containing members.
- **DocObject**: A recursive structure for classes, functions, and attributes.
Overview
--------
These classes are designed to be renderer-agnostic, allowing the same internal
representation to be transformed into various output formats (currently MkDocs).
The model layer forms the central intermediate representation used throughout
doc-forge. Python modules and objects discovered during introspection are
converted into a hierarchy of documentation models that can later be rendered
into different documentation formats.
Key components:
- **Project** – Root container representing an entire documented codebase.
- **Module** – Representation of a Python module or package containing
documented members.
- **DocObject** – Recursive structure representing Python objects such as
classes, functions, methods, and attributes.
These models are intentionally **renderer-agnostic**, allowing the same
documentation structure to be transformed into multiple output formats
(e.g., MkDocs, MCP, or other renderers).
---
"""
from .project import Project

43
docforge/models/module.py
View File

@@ -1,7 +1,10 @@
"""
This module defines the Module class, which represents a Python module or package
in the doc-forge documentation models. It acts as a container for top-level
documented objects.
Documentation model representing a Python module or package.
This module defines the ``Module`` class used in the doc-forge documentation
model. A ``Module`` acts as a container for top-level documented objects
(classes, functions, variables, and other members) discovered during
introspection.
"""
from typing import Dict, Iterable, Optional
@@ -11,12 +14,17 @@ from docforge.models.object import DocObject
class Module:
"""
Represents a documented Python module or package.
Representation of a documented Python module or package.
A ``Module`` stores metadata about the module itself and maintains a
collection of top-level documentation objects discovered during
introspection.
Attributes:
path: Dotted import path of the module.
docstring: Module-level docstring content.
members: Dictionary mapping object names to their DocObject representations.
docstring: Module-level documentation string, if present.
members: Mapping of object names to their corresponding
``DocObject`` representations.
"""
def __init__(
@@ -25,11 +33,11 @@ class Module:
docstring: Optional[str] = None,
) -> None:
"""
Initialize a new Module.
Initialize a Module instance.
Args:
path: The dotted path of the module.
docstring: The module's docstring, if any.
path: Dotted import path identifying the module.
docstring: Module-level documentation text, if available.
"""
self.path = path
self.docstring = docstring
@@ -40,27 +48,32 @@ class Module:
Add a documented object to the module.
Args:
obj: The object to add.
obj: Documentation object to register as a top-level
member of the module.
"""
self.members[obj.name] = obj
def get_object(self, name: str) -> DocObject:
"""
Retrieve a member object by name.
Retrieve a documented object by name.
Args:
name: The name of the object.
name: Name of the object to retrieve.
Returns:
The requested DocObject.
The corresponding ``DocObject`` instance.
Raises:
KeyError: If no object with the given name exists.
"""
return self.members[name]
def get_all_objects(self) -> Iterable[DocObject]:
"""
Get all top-level objects in the module.
Return all top-level documentation objects in the module.
Returns:
An iterable of DocObject instances.
An iterable of ``DocObject`` instances representing the
module's public members.
"""
return self.members.values()

66
docforge/models/object.py
View File

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

39
docforge/models/project.py
View File

@@ -1,6 +1,9 @@
"""
This module defines the Project class, the top-level container for a documented
project. It aggregates multiple Module instances into a single named entity.
Documentation model representing a project.
This module defines the ``Project`` class, the top-level container used by
doc-forge to represent a documented codebase. A ``Project`` aggregates multiple
modules and provides access to them through a unified interface.
"""
from typing import Dict, Iterable
@@ -10,29 +13,32 @@ from docforge.models.module import Module
class Project:
"""
Represents a documentation project, serving as a container for modules.
Representation of a documentation project.
A ``Project`` serves as the root container for all modules discovered during
introspection. Each module is stored by its dotted import path.
Attributes:
name: Name of the project.
modules: Dictionary mapping module paths to Module instances.
modules: Mapping of module paths to ``Module`` instances.
"""
def __init__(self, name: str) -> None:
"""
Initialize a new Project.
Initialize a Project instance.
Args:
name: The name of the project.
name: Name used to identify the documentation project.
"""
self.name = name
self.modules: Dict[str, Module] = {}
def add_module(self, module: Module) -> None:
"""
Add a module to the project.
Register a module in the project.
Args:
module: The module to add.
module: Module instance to add to the project.
"""
self.modules[module.path] = module
@@ -41,27 +47,30 @@ class Project:
Retrieve a module by its dotted path.
Args:
path: The dotted path of the module (e.g., 'pkg.mod').
path: Fully qualified dotted module path (for example ``pkg.module``).
Returns:
The requested Module.
The corresponding ``Module`` instance.
Raises:
KeyError: If the module does not exist in the project.
"""
return self.modules[path]
def get_all_modules(self) -> Iterable[Module]:
"""
Get all modules in the project.
Return all modules contained in the project.
Returns:
An iterable of Module objects.
An iterable of ``Module`` instances.
"""
return self.modules.values()
def get_module_list(self) -> list[str]:
"""
Get the list of all module dotted paths.
Return the list of module import paths.
Returns:
A list of module paths.
A list containing the dotted paths of all modules in the project.
"""
return list(self.modules.keys())
return list(self.modules.keys())