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

aetos · 2026-03-07T10:49:14Z

aetos commented

2026-03-07 10:49:14 +00:00

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.

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.

# 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.

aetos added 5 commits 2026-03-07 10:49:15 +00:00

google styled doc string and create README.md using package doc string 219d6f9f87

updated tests for readme generations 73b15cc3ab

updated doc strings 17d39a3e88

updated template for mkdocs and rendered MCP docs and site 7f5dd7e5be

code segment changes f4f3455aba

aetos merged commit b6306baafc into main

2026-03-07 10:50:19 +00:00

aetos deleted branch google-styled-doc

2026-03-07 10:50:19 +00:00

aetos referenced this issue from a commit

2026-03-07 10:50:20 +00:00