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

27
docforge/nav/__init__.py
View File

@@ -1,17 +1,26 @@
"""
# Navigation Layer
Navigation layer for doc-forge.
The `docforge.nav` package manages the mapping between the logical documentation
structure and the physical files on disk.
The ``docforge.nav`` package manages the relationship between the logical
documentation structure defined by the user and the physical documentation
files generated on disk.
## Workflow
---
1. **Spec Definition**: Users define navigation intent in `docforge.nav.yml`.
2. **Resolution**: `resolve_nav` matches patterns in the spec to generated `.md` files.
3. **Emission**: `MkDocsNavEmitter` produces the final YAML structure for `mkdocs.yml`.
Workflow
--------
This abstraction allows doc-forge to support complex grouping and ordering
independently of the source code's physical layout.
1. **Specification** – Users define navigation intent in ``docforge.nav.yml``.
2. **Resolution** – ``resolve_nav`` expands patterns and matches them against
generated Markdown files.
3. **Emission** – ``MkDocsNavEmitter`` converts the resolved structure into
the YAML navigation format required by ``mkdocs.yml``.
This layer separates documentation organization from the underlying source
code layout, enabling flexible grouping, ordering, and navigation structures
independent of module hierarchy.
---
"""
from .spec import NavSpec, load_nav_spec

39
docforge/nav/mkdocs.py
View File

@@ -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]

60
docforge/nav/resolver.py
View File

@@ -1,7 +1,8 @@
"""
This module contains the logic for resolving a NavSpec against the physical
filesystem. It expands globs and validates that all referenced documents
actually exist on disk.
Navigation resolution utilities.
This module resolves a ``NavSpec`` against the filesystem by expanding glob
patterns and validating that referenced documentation files exist.
"""
from pathlib import Path
@@ -14,12 +15,15 @@ from docforge.nav.spec import NavSpec
class ResolvedNav:
"""
Represents a navigation structure where all patterns and paths have been
resolved against the actual filesystem contents.
Resolved navigation structure.
A ``ResolvedNav`` represents navigation data after glob patterns have been
expanded and paths validated against the filesystem.
Attributes:
home: Resolved relative path to the home page.
groups: Mapping of group titles to lists of absolute or relative Path objects.
home: Relative path to the documentation home page.
groups: Mapping of navigation group titles to lists of resolved
documentation file paths.
"""
def __init__(
@@ -32,9 +36,9 @@ class ResolvedNav:
Initialize a ResolvedNav instance.
Args:
home: The relative path to the project home page.
groups: A mapping of group names to their resolved filesystem paths.
docs_root: The root documentation directory.
home: Relative path to the home page within the documentation root.
groups: Mapping of group titles to resolved documentation file paths.
docs_root: Root directory of the documentation source files.
"""
self.home = home
self.groups = groups
@@ -42,15 +46,20 @@ class ResolvedNav:
def all_files(self) -> Iterable[Path]:
"""
Get an iterable of all resolved files in the navigation structure.
Iterate over all files referenced by the navigation structure.
Returns:
An iterable of Path objects.
An iterable of ``Path`` objects representing documentation files.
Raises:
RuntimeError: If the home page is defined but the documentation
root is not available for resolution.
"""
if self.home:
if self._docs_root is None:
raise RuntimeError("docs_root is required to resolve home path")
yield self._docs_root / self.home
for paths in self.groups.values():
for p in paths:
yield p
@@ -61,34 +70,37 @@ def resolve_nav(
docs_root: Path,
) -> ResolvedNav:
"""
Create a ResolvedNav by processing a NavSpec against the filesystem.
This expands globs and validates the existence of referenced files.
Resolve a navigation specification against the filesystem.
The function expands glob patterns defined in a ``NavSpec`` and verifies
that referenced documentation files exist within the documentation root.
Args:
spec: The navigation specification to resolve.
docs_root: The root directory for documentation files.
spec: Navigation specification describing documentation layout.
docs_root: Root directory containing documentation Markdown files.
Returns:
A ResolvedNav instance.
A ``ResolvedNav`` instance containing validated navigation paths.
Raises:
FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist.
FileNotFoundError: If the documentation root does not exist or a
navigation pattern does not match any files.
"""
if not docs_root.exists():
raise FileNotFoundError(docs_root)
def resolve_pattern(pattern: str) -> List[Path]:
"""
Resolve a single glob pattern relative to the docs_root.
Resolve a glob pattern relative to the documentation root.
Args:
pattern: The glob pattern to resolve.
pattern: Glob pattern used to match documentation files.
Returns:
A sorted list of matching Path objects.
A sorted list of matching ``Path`` objects.
Raises:
FileNotFoundError: If the pattern doesn't match any files.
FileNotFoundError: If the pattern does not match any files.
"""
full = docs_root / pattern
matches = sorted(
@@ -100,7 +112,7 @@ def resolve_nav(
return matches
# Resolve home
# Resolve home page
home: str | None = None
if spec.home:
home_path = docs_root / spec.home
@@ -108,7 +120,7 @@ def resolve_nav(
raise FileNotFoundError(spec.home)
home = spec.home
# Resolve groups
# Resolve navigation groups
resolved_groups: Dict[str, List[Path]] = {}
for group, patterns in spec.groups.items():

57
docforge/nav/spec.py
View File

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