aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
google-docs
doc-forge/mcp_docs/modules/docforge.nav.json
Vishesh 'ironeagle' Bangotra b6306baafc 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>
2026-03-07 10:50:18 +00:00

402 lines
24 KiB
JSON
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

{
"module": "docforge.nav",
"content": {
"path": "docforge.nav",
"docstring": "Navigation layer for doc-forge.\n\nThe ``docforge.nav`` package manages the relationship between the logical\ndocumentation structure defined by the user and the physical documentation\nfiles generated on disk.\n\n---\n\nWorkflow\n--------\n\n1. **Specification** – Users define navigation intent in ``docforge.nav.yml``.\n2. **Resolution** – ``resolve_nav`` expands patterns and matches them against\n generated Markdown files.\n3. **Emission** – ``MkDocsNavEmitter`` converts the resolved structure into\n the YAML navigation format required by ``mkdocs.yml``.\n\nThis layer separates documentation organization from the underlying source\ncode layout, enabling flexible grouping, ordering, and navigation structures\nindependent of module hierarchy.\n\n---",
"objects": {
"NavSpec": {
"name": "NavSpec",
"kind": "class",
"path": "docforge.nav.NavSpec",
"signature": "<bound method Alias.signature of Alias('NavSpec', 'docforge.nav.spec.NavSpec')>",
"docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page (for example\n ``index.md``).\n groups: Mapping of navigation group titles to lists of file patterns\n or glob expressions.",
"members": {
"home": {
"name": "home",
"kind": "attribute",
"path": "docforge.nav.NavSpec.home",
"signature": "<bound method Alias.signature of Alias('home', 'docforge.nav.spec.NavSpec.home')>",
"docstring": null
},
"groups": {
"name": "groups",
"kind": "attribute",
"path": "docforge.nav.NavSpec.groups",
"signature": "<bound method Alias.signature of Alias('groups', 'docforge.nav.spec.NavSpec.groups')>",
"docstring": null
},
"load": {
"name": "load",
"kind": "function",
"path": "docforge.nav.NavSpec.load",
"signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>",
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification."
},
"all_patterns": {
"name": "all_patterns",
"kind": "function",
"path": "docforge.nav.NavSpec.all_patterns",
"signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>",
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries."
}
}
},
"load_nav_spec": {
"name": "load_nav_spec",
"kind": "function",
"path": "docforge.nav.load_nav_spec",
"signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.spec.load_nav_spec')>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid."
},
"ResolvedNav": {
"name": "ResolvedNav",
"kind": "class",
"path": "docforge.nav.ResolvedNav",
"signature": "<bound method Alias.signature of Alias('ResolvedNav', 'docforge.nav.resolver.ResolvedNav')>",
"docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page.\n groups: Mapping of navigation group titles to lists of resolved\n documentation file paths.",
"members": {
"home": {
"name": "home",
"kind": "attribute",
"path": "docforge.nav.ResolvedNav.home",
"signature": "<bound method Alias.signature of Alias('home', 'docforge.nav.resolver.ResolvedNav.home')>",
"docstring": null
},
"groups": {
"name": "groups",
"kind": "attribute",
"path": "docforge.nav.ResolvedNav.groups",
"signature": "<bound method Alias.signature of Alias('groups', 'docforge.nav.resolver.ResolvedNav.groups')>",
"docstring": null
},
"all_files": {
"name": "all_files",
"kind": "function",
"path": "docforge.nav.ResolvedNav.all_files",
"signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>",
"docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution."
}
}
},
"resolve_nav": {
"name": "resolve_nav",
"kind": "function",
"path": "docforge.nav.resolve_nav",
"signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolver.resolve_nav')>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n FileNotFoundError: If the documentation root does not exist or a\n navigation pattern does not match any files."
},
"MkDocsNavEmitter": {
"name": "MkDocsNavEmitter",
"kind": "class",
"path": "docforge.nav.MkDocsNavEmitter",
"signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.nav.mkdocs.MkDocsNavEmitter')>",
"docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.",
"members": {
"emit": {
"name": "emit",
"kind": "function",
"path": "docforge.nav.MkDocsNavEmitter.emit",
"signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages."
}
}
},
"mkdocs": {
"name": "mkdocs",
"kind": "module",
"path": "docforge.nav.mkdocs",
"signature": null,
"docstring": "MkDocs navigation emitter.\n\nThis module provides the ``MkDocsNavEmitter`` class, which converts a\n``ResolvedNav`` instance into the navigation structure required by the\nMkDocs ``nav`` configuration.",
"members": {
"Path": {
"name": "Path",
"kind": "alias",
"path": "docforge.nav.mkdocs.Path",
"signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
"docstring": null
},
"List": {
"name": "List",
"kind": "alias",
"path": "docforge.nav.mkdocs.List",
"signature": "<bound method Alias.signature of Alias('List', 'typing.List')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "docforge.nav.mkdocs.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null
},
"Any": {
"name": "Any",
"kind": "alias",
"path": "docforge.nav.mkdocs.Any",
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
},
"ResolvedNav": {
"name": "ResolvedNav",
"kind": "class",
"path": "docforge.nav.mkdocs.ResolvedNav",
"signature": "<bound method Alias.signature of Alias('ResolvedNav', 'docforge.nav.resolver.ResolvedNav')>",
"docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page.\n groups: Mapping of navigation group titles to lists of resolved\n documentation file paths.",
"members": {
"home": {
"name": "home",
"kind": "attribute",
"path": "docforge.nav.mkdocs.ResolvedNav.home",
"signature": "<bound method Alias.signature of Alias('home', 'docforge.nav.resolver.ResolvedNav.home')>",
"docstring": null
},
"groups": {
"name": "groups",
"kind": "attribute",
"path": "docforge.nav.mkdocs.ResolvedNav.groups",
"signature": "<bound method Alias.signature of Alias('groups', 'docforge.nav.resolver.ResolvedNav.groups')>",
"docstring": null
},
"all_files": {
"name": "all_files",
"kind": "function",
"path": "docforge.nav.mkdocs.ResolvedNav.all_files",
"signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>",
"docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution."
}
}
},
"MkDocsNavEmitter": {
"name": "MkDocsNavEmitter",
"kind": "class",
"path": "docforge.nav.mkdocs.MkDocsNavEmitter",
"signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 15, 81)>",
"docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.",
"members": {
"emit": {
"name": "emit",
"kind": "function",
"path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit",
"signature": "<bound method Function.signature of Function('emit', 23, 51)>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages."
}
}
}
}
},
"resolver": {
"name": "resolver",
"kind": "module",
"path": "docforge.nav.resolver",
"signature": null,
"docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.",
"members": {
"Path": {
"name": "Path",
"kind": "alias",
"path": "docforge.nav.resolver.Path",
"signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "docforge.nav.resolver.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null
},
"Iterable": {
"name": "Iterable",
"kind": "alias",
"path": "docforge.nav.resolver.Iterable",
"signature": "<bound method Alias.signature of Alias('Iterable', 'typing.Iterable')>",
"docstring": null
},
"List": {
"name": "List",
"kind": "alias",
"path": "docforge.nav.resolver.List",
"signature": "<bound method Alias.signature of Alias('List', 'typing.List')>",
"docstring": null
},
"glob": {
"name": "glob",
"kind": "alias",
"path": "docforge.nav.resolver.glob",
"signature": "<bound method Alias.signature of Alias('glob', 'glob')>",
"docstring": null
},
"NavSpec": {
"name": "NavSpec",
"kind": "class",
"path": "docforge.nav.resolver.NavSpec",
"signature": "<bound method Alias.signature of Alias('NavSpec', 'docforge.nav.spec.NavSpec')>",
"docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page (for example\n ``index.md``).\n groups: Mapping of navigation group titles to lists of file patterns\n or glob expressions.",
"members": {
"home": {
"name": "home",
"kind": "attribute",
"path": "docforge.nav.resolver.NavSpec.home",
"signature": "<bound method Alias.signature of Alias('home', 'docforge.nav.spec.NavSpec.home')>",
"docstring": null
},
"groups": {
"name": "groups",
"kind": "attribute",
"path": "docforge.nav.resolver.NavSpec.groups",
"signature": "<bound method Alias.signature of Alias('groups', 'docforge.nav.spec.NavSpec.groups')>",
"docstring": null
},
"load": {
"name": "load",
"kind": "function",
"path": "docforge.nav.resolver.NavSpec.load",
"signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>",
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification."
},
"all_patterns": {
"name": "all_patterns",
"kind": "function",
"path": "docforge.nav.resolver.NavSpec.all_patterns",
"signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>",
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries."
}
}
},
"ResolvedNav": {
"name": "ResolvedNav",
"kind": "class",
"path": "docforge.nav.resolver.ResolvedNav",
"signature": "<bound method Class.signature of Class('ResolvedNav', 16, 65)>",
"docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page.\n groups: Mapping of navigation group titles to lists of resolved\n documentation file paths.",
"members": {
"home": {
"name": "home",
"kind": "attribute",
"path": "docforge.nav.resolver.ResolvedNav.home",
"signature": null,
"docstring": null
},
"groups": {
"name": "groups",
"kind": "attribute",
"path": "docforge.nav.resolver.ResolvedNav.groups",
"signature": null,
"docstring": null
},
"all_files": {
"name": "all_files",
"kind": "function",
"path": "docforge.nav.resolver.ResolvedNav.all_files",
"signature": "<bound method Function.signature of Function('all_files', 47, 65)>",
"docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution."
}
}
},
"resolve_nav": {
"name": "resolve_nav",
"kind": "function",
"path": "docforge.nav.resolver.resolve_nav",
"signature": "<bound method Function.signature of Function('resolve_nav', 68, 136)>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n FileNotFoundError: If the documentation root does not exist or a\n navigation pattern does not match any files."
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "docforge.nav.resolver.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
}
}
},
"spec": {
"name": "spec",
"kind": "module",
"path": "docforge.nav.spec",
"signature": null,
"docstring": "Navigation specification model.\n\nThis module defines the ``NavSpec`` class, which represents the navigation\nstructure defined by the user in the doc-forge navigation specification\n(typically ``docforge.nav.yml``).",
"members": {
"Path": {
"name": "Path",
"kind": "alias",
"path": "docforge.nav.spec.Path",
"signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "docforge.nav.spec.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null
},
"List": {
"name": "List",
"kind": "alias",
"path": "docforge.nav.spec.List",
"signature": "<bound method Alias.signature of Alias('List', 'typing.List')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "docforge.nav.spec.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"yaml": {
"name": "yaml",
"kind": "alias",
"path": "docforge.nav.spec.yaml",
"signature": "<bound method Alias.signature of Alias('yaml', 'yaml')>",
"docstring": null
},
"NavSpec": {
"name": "NavSpec",
"kind": "class",
"path": "docforge.nav.spec.NavSpec",
"signature": "<bound method Class.signature of Class('NavSpec', 15, 104)>",
"docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page (for example\n ``index.md``).\n groups: Mapping of navigation group titles to lists of file patterns\n or glob expressions.",
"members": {
"home": {
"name": "home",
"kind": "attribute",
"path": "docforge.nav.spec.NavSpec.home",
"signature": null,
"docstring": null
},
"groups": {
"name": "groups",
"kind": "attribute",
"path": "docforge.nav.spec.NavSpec.groups",
"signature": null,
"docstring": null
},
"load": {
"name": "load",
"kind": "function",
"path": "docforge.nav.spec.NavSpec.load",
"signature": "<bound method Function.signature of Function('load', 45, 86)>",
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification."
},
"all_patterns": {
"name": "all_patterns",
"kind": "function",
"path": "docforge.nav.spec.NavSpec.all_patterns",
"signature": "<bound method Function.signature of Function('all_patterns', 88, 104)>",
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries."
}
}
},
"load_nav_spec": {
"name": "load_nav_spec",
"kind": "function",
"path": "docforge.nav.spec.load_nav_spec",
"signature": "<bound method Function.signature of Function('load_nav_spec', 107, 135)>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid."
}
}
}
}
}
}
Reference in New Issue View Git Blame Copy Permalink