Vishesh 'ironeagle' Bangotra
b6306baafc
# 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>
82 lines
2.7 KiB
Python
82 lines
2.7 KiB
Python
"""
|
|
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
|
|
from typing import List, Dict, Any
|
|
|
|
from docforge.nav.resolver import ResolvedNav
|
|
|
|
|
|
class MkDocsNavEmitter:
|
|
"""
|
|
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 navigation structure for ``mkdocs.yml``.
|
|
|
|
Args:
|
|
nav: Resolved navigation data describing documentation groups
|
|
and their associated Markdown files.
|
|
|
|
Returns:
|
|
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]] = []
|
|
|
|
# Home entry (semantic path)
|
|
if nav.home:
|
|
result.append({"Home": nav.home})
|
|
|
|
# Group entries
|
|
for group, paths in nav.groups.items():
|
|
entries: List[str] = []
|
|
for p in paths:
|
|
# Convert filesystem path back to docs-relative path
|
|
rel_path = self._to_relative(p, nav._docs_root)
|
|
entries.append(rel_path)
|
|
result.append({group: entries})
|
|
|
|
return result
|
|
|
|
def _to_relative(self, path: Path, docs_root: Path | None) -> str:
|
|
"""
|
|
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: Filesystem path to convert.
|
|
docs_root: Root directory of the documentation sources.
|
|
|
|
Returns:
|
|
POSIX-style path relative to the documentation root.
|
|
"""
|
|
if docs_root and path.is_absolute():
|
|
try:
|
|
path = path.relative_to(docs_root.resolve())
|
|
except ValueError:
|
|
pass
|
|
elif docs_root:
|
|
# Handle relative paths (e.g. starting with 'docs/')
|
|
path_str = path.as_posix()
|
|
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]
|