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

30
docforge/loaders/__init__.py
View File

@@ -1,17 +1,27 @@
"""
# Loader Layer
Loader layer for doc-forge.
The `docforge.loaders` package is responsible for discovering Python source files
and extracting their documentation using static analysis.
The ``docforge.loaders`` package is responsible for discovering Python modules
and extracting documentation data using static analysis.
## Core Features
---
- **Discovery**: Automatically find all modules and packages in a project
directory.
- **Introspection**: Uses `griffe` to parse docstrings, signatures, and
hierarchical relationships without executing the code.
- **Filtering**: Automatically excludes private members (prefixed with `_`) to
ensure clean public documentation.
Overview
--------
This layer converts Python source code into an intermediate documentation
model used by doc-forge. It performs module discovery, introspection, and
initial filtering before the data is passed to the core documentation models.
Core capabilities include:
- **Module discovery** – Locate Python modules and packages within a project.
- **Static introspection** – Parse docstrings, signatures, and object
hierarchies using the ``griffe`` library without executing the code.
- **Public API filtering** – Exclude private members (names prefixed with
``_``) to produce clean public documentation structures.
---
"""
from .griffe_loader import GriffeLoader, discover_module_paths

112
docforge/loaders/griffe_loader.py
View File

@@ -1,6 +1,9 @@
"""
This module provides the GriffeLoader, which uses the 'griffe' library to
introspect Python source code and populate the doc-forge Project models.
Utilities for loading and introspecting Python modules using Griffe.
This module provides the ``GriffeLoader`` class and helper utilities used to
discover Python modules, introspect their structure, and convert the results
into doc-forge documentation models.
"""
import logging
@@ -25,19 +28,27 @@ def discover_module_paths(
project_root: Path | None = None,
) -> List[str]:
"""
Discover all Python modules under a package via filesystem traversal.
Discover Python modules within a package directory.
Rules:
- Directory with __init__.py is treated as a package.
- Any .py file is treated as a module.
- All paths are converted to dotted module paths.
The function scans the filesystem for ``.py`` files inside the specified
package and converts them into dotted module import paths.
Discovery rules:
- Directories containing ``__init__.py`` are treated as packages.
- Each ``.py`` file is treated as a module.
- Results are returned as dotted import paths.
Args:
module_name: The name of the package to discover.
project_root: The root directory of the project. Defaults to current working directory.
module_name: Top-level package name to discover modules from.
project_root: Root directory used to resolve module paths. If not
provided, the current working directory is used.
Returns:
A sorted list of dotted module paths.
A sorted list of unique dotted module import paths.
Raises:
FileNotFoundError: If the specified package directory does not exist.
"""
if project_root is None:
@@ -64,12 +75,19 @@ def discover_module_paths(
class GriffeLoader:
"""
Loads Python modules and extracts documentation using the Griffe introspection engine.
Load Python modules using Griffe and convert them into doc-forge models.
This loader uses the Griffe introspection engine to analyze Python source
code and transform the extracted information into ``Project``, ``Module``,
and ``DocObject`` instances used by doc-forge.
"""
def __init__(self) -> None:
"""
Initialize the GriffeLoader.
Initialize the Griffe-backed loader.
Creates an internal Griffe loader instance with dedicated collections
for modules and source lines.
"""
self._loader = _GriffeLoader(
modules_collection=ModulesCollection(),
@@ -77,21 +95,32 @@ class GriffeLoader:
)
def load_project(
self,
module_paths: List[str],
project_name: Optional[str] = None,
skip_import_errors: bool = None,
self,
module_paths: List[str],
project_name: Optional[str] = None,
skip_import_errors: bool = None,
) -> Project:
"""
Load multiple modules and combine them into a single Project models.
Load multiple modules and assemble them into a Project model.
Each module path is introspected and converted into a ``Module``
instance. All modules are then aggregated into a single ``Project``
object.
Args:
module_paths: A list of dotted paths to the modules to load.
project_name: Optional name for the project. Defaults to the first module name.
skip_import_errors: If True, modules that fail to import will be skipped.
module_paths: List of dotted module import paths to load.
project_name: Optional override for the project name. Defaults
to the top-level name of the first module.
skip_import_errors: If True, modules that fail to load will be
skipped instead of raising an error.
Returns:
A Project instance containing the loaded modules.
A populated ``Project`` instance containing the loaded modules.
Raises:
ValueError: If no module paths are provided.
ImportError: If a module fails to load and
``skip_import_errors`` is False.
"""
if not module_paths:
raise ValueError("At least one module path must be provided")
@@ -116,13 +145,16 @@ class GriffeLoader:
def load_module(self, path: str) -> Module:
"""
Load a single module and convert its introspection data into the docforge models.
Load and convert a single Python module.
The module is introspected using Griffe and then transformed into
a doc-forge ``Module`` model.
Args:
path: The dotted path of the module to load.
path: Dotted import path of the module.
Returns:
A Module instance.
A populated ``Module`` instance.
"""
self._loader.load(path)
griffe_module = self._loader.modules_collection[path]
@@ -135,13 +167,16 @@ class GriffeLoader:
def _convert_module(self, obj: Object) -> Module:
"""
Convert a Griffe Object (module) into a docforge Module.
Convert a Griffe module object into a doc-forge Module.
All public members of the module are recursively converted into
``DocObject`` instances.
Args:
obj: The Griffe Object representing the module.
obj: Griffe object representing the module.
Returns:
A populated Module instance.
A populated ``Module`` model.
"""
module = Module(
path=obj.path,
@@ -158,13 +193,17 @@ class GriffeLoader:
def _convert_object(self, obj: Object) -> DocObject:
"""
Recursively convert a Griffe Object into a DocObject hierarchy.
Convert a Griffe object into a doc-forge DocObject.
The conversion preserves the object's metadata such as name,
kind, path, signature, and docstring. Child members are processed
recursively.
Args:
obj: The Griffe Object to convert.
obj: Griffe object representing a documented Python object.
Returns:
A DocObject instance.
A ``DocObject`` instance representing the converted object.
"""
kind = obj.kind.value
signature = self._safe_signature(obj)
@@ -193,13 +232,13 @@ class GriffeLoader:
def _safe_docstring(self, obj: Object) -> Optional[str]:
"""
Safely retrieve the docstring value from a Griffe object.
Safely extract a docstring from a Griffe object.
Args:
obj: The Griffe Object to inspect.
obj: Griffe object to inspect.
Returns:
The raw docstring string, or None if missing or unresolvable.
The raw docstring text if available, otherwise ``None``.
"""
try:
return obj.docstring.value if obj.docstring else None
@@ -208,13 +247,14 @@ class GriffeLoader:
def _safe_signature(self, obj: Object) -> Optional[str]:
"""
Safely retrieve the signature string from a Griffe object.
Safely extract the signature of a Griffe object.
Args:
obj: The Griffe Object to inspect.
obj: Griffe object to inspect.
Returns:
The string representation of the signature, or None.
String representation of the object's signature if available,
otherwise ``None``.
"""
try:
if hasattr(obj, "signature") and obj.signature: