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>
This commit is contained in:
@@ -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():
|
||||
|
||||
Reference in New Issue
Block a user