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>
92 lines
1.9 KiB
YAML
92 lines
1.9 KiB
YAML
theme:
|
|
name: material
|
|
palette:
|
|
- scheme: slate
|
|
primary: deep purple
|
|
accent: cyan
|
|
font:
|
|
text: Inter
|
|
code: JetBrains Mono
|
|
features:
|
|
- navigation.sections
|
|
- navigation.expand
|
|
- navigation.top
|
|
- navigation.instant
|
|
- navigation.tracking
|
|
- navigation.indexes
|
|
- content.code.copy
|
|
- content.code.annotate
|
|
- content.tabs.link
|
|
- content.action.edit
|
|
- search.highlight
|
|
- search.share
|
|
- search.suggest
|
|
plugins:
|
|
- search
|
|
- mkdocstrings:
|
|
handlers:
|
|
python:
|
|
paths:
|
|
- .
|
|
options:
|
|
docstring_style: google
|
|
show_source: false
|
|
show_signature_annotations: true
|
|
separate_signature: true
|
|
merge_init_into_class: true
|
|
inherited_members: true
|
|
annotations_path: brief
|
|
show_root_heading: true
|
|
group_by_category: true
|
|
show_category_heading: true
|
|
show_object_full_path: false
|
|
show_symbol_type_heading: true
|
|
markdown_extensions:
|
|
- pymdownx.superfences
|
|
- pymdownx.inlinehilite
|
|
- pymdownx.snippets
|
|
- admonition
|
|
- pymdownx.details
|
|
- pymdownx.superfences
|
|
- pymdownx.highlight:
|
|
linenums: true
|
|
anchor_linenums: true
|
|
line_spans: __span
|
|
pygments_lang_class: true
|
|
- pymdownx.tabbed:
|
|
alternate_style: true
|
|
- pymdownx.tasklist:
|
|
custom_checkbox: true
|
|
- tables
|
|
- footnotes
|
|
- pymdownx.caret
|
|
- pymdownx.tilde
|
|
- pymdownx.mark
|
|
site_name: docforge
|
|
nav:
|
|
- Home: index.md
|
|
- Loaders:
|
|
- loaders/index.md
|
|
- loaders/griffe_loader.md
|
|
- Models:
|
|
- models/index.md
|
|
- models/module.md
|
|
- models/object.md
|
|
- models/project.md
|
|
- Navigation:
|
|
- nav/index.md
|
|
- nav/spec.md
|
|
- nav/resolver.md
|
|
- nav/mkdocs.md
|
|
- Renderers:
|
|
- renderers/index.md
|
|
- renderers/base.md
|
|
- renderers/mkdocs_renderer.md
|
|
- renderers/mcp_renderer.md
|
|
- CLI:
|
|
- cli/index.md
|
|
- cli/main.md
|
|
- cli/commands.md
|
|
- cli/mcp_utils.md
|
|
- cli/mkdocs_utils.md
|