aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated template for mkdocs and rendered MCP docs and site

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-03-07 16:07:18 +05:30
parent 17d39a3e88
commit 7f5dd7e5be
31 changed files with 1308 additions and 936 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
mcp_docs/modules/docforge.nav.json
View File

@@ -2,14 +2,14 @@
"module": "docforge.nav",
"content": {
"path": "docforge.nav",
"docstring": "# Navigation Layer\n\nThe `docforge.nav` package manages the mapping between the logical documentation\nstructure and the physical files on disk.\n\n## Workflow\n\n1. **Spec Definition**: Users define navigation intent in `docforge.nav.yml`.\n2. **Resolution**: `resolve_nav` matches patterns in the spec to generated `.md` files.\n3. **Emission**: `MkDocsNavEmitter` produces the final YAML structure for `mkdocs.yml`.\n\nThis abstraction allows doc-forge to support complex grouping and ordering\nindependently of the source code's physical layout.",
"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 the docforge navigation specification file.\n\nAttributes:\n home: Path to the home document (e.g., 'index.md').\n groups: Mapping of group titles to lists of path patterns/globs.",
"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",
@@ -30,14 +30,14 @@
"kind": "function",
"path": "docforge.nav.NavSpec.load",
"signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>",
"docstring": "Load a NavSpec from a YAML file.\n\nArgs:\n path: The filesystem path to the YAML file.\n\nReturns:\n A NavSpec instance.\n\nRaises:\n FileNotFoundError: If the path does not exist.\n ValueError: If the file content is not a valid NavSpec mapping."
"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": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)."
"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."
}
}
},
@@ -46,14 +46,14 @@
"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": "Utility function to load a NavSpec from a file.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A loaded NavSpec instance."
"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": "Represents a navigation structure where all patterns and paths have been\nresolved against the actual filesystem contents.\n\nAttributes:\n home: Resolved relative path to the home page.\n groups: Mapping of group titles to lists of absolute or relative Path objects.",
"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",
@@ -74,7 +74,7 @@
"kind": "function",
"path": "docforge.nav.ResolvedNav.all_files",
"signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>",
"docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects."
"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."
}
}
},
@@ -83,21 +83,21 @@
"kind": "function",
"path": "docforge.nav.resolve_nav",
"signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolver.resolve_nav')>",
"docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n spec: The navigation specification to resolve.\n docs_root: The root directory for documentation files.\n\nReturns:\n A ResolvedNav instance.\n\nRaises:\n FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist."
"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": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
"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 list of navigation entries for mkdocs.yml.\n\nArgs:\n nav: The resolved navigation data.\n\nReturns:\n A list of dictionary mappings representing the MkDocs navigation."
"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."
}
}
},
@@ -106,7 +106,7 @@
"kind": "module",
"path": "docforge.nav.mkdocs",
"signature": null,
"docstring": "This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance\ninto the specific YAML-ready list structure expected by the MkDocs 'nav'\nconfiguration.",
"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",
@@ -141,7 +141,7 @@
"kind": "class",
"path": "docforge.nav.mkdocs.ResolvedNav",
"signature": "<bound method Alias.signature of Alias('ResolvedNav', 'docforge.nav.resolver.ResolvedNav')>",
"docstring": "Represents a navigation structure where all patterns and paths have been\nresolved against the actual filesystem contents.\n\nAttributes:\n home: Resolved relative path to the home page.\n groups: Mapping of group titles to lists of absolute or relative Path objects.",
"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",
@@ -162,7 +162,7 @@
"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": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects."
"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."
}
}
},
@@ -170,15 +170,15 @@
"name": "MkDocsNavEmitter",
"kind": "class",
"path": "docforge.nav.mkdocs.MkDocsNavEmitter",
"signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 13, 72)>",
"docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
"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', 19, 44)>",
"docstring": "Generate a list of navigation entries for mkdocs.yml.\n\nArgs:\n nav: The resolved navigation data.\n\nReturns:\n A list of dictionary mappings representing the MkDocs navigation."
"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."
}
}
}
@@ -189,7 +189,7 @@
"kind": "module",
"path": "docforge.nav.resolver",
"signature": null,
"docstring": "This module contains the logic for resolving a NavSpec against the physical\nfilesystem. It expands globs and validates that all referenced documents\nactually exist on disk.",
"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",
@@ -231,7 +231,7 @@
"kind": "class",
"path": "docforge.nav.resolver.NavSpec",
"signature": "<bound method Alias.signature of Alias('NavSpec', 'docforge.nav.spec.NavSpec')>",
"docstring": "Parsed representation of the docforge navigation specification file.\n\nAttributes:\n home: Path to the home document (e.g., 'index.md').\n groups: Mapping of group titles to lists of path patterns/globs.",
"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",
@@ -252,14 +252,14 @@
"kind": "function",
"path": "docforge.nav.resolver.NavSpec.load",
"signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>",
"docstring": "Load a NavSpec from a YAML file.\n\nArgs:\n path: The filesystem path to the YAML file.\n\nReturns:\n A NavSpec instance.\n\nRaises:\n FileNotFoundError: If the path does not exist.\n ValueError: If the file content is not a valid NavSpec mapping."
"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": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)."
"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."
}
}
},
@@ -267,8 +267,8 @@
"name": "ResolvedNav",
"kind": "class",
"path": "docforge.nav.resolver.ResolvedNav",
"signature": "<bound method Class.signature of Class('ResolvedNav', 15, 56)>",
"docstring": "Represents a navigation structure where all patterns and paths have been\nresolved against the actual filesystem contents.\n\nAttributes:\n home: Resolved relative path to the home page.\n groups: Mapping of group titles to lists of absolute or relative Path objects.",
"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",
@@ -288,8 +288,8 @@
"name": "all_files",
"kind": "function",
"path": "docforge.nav.resolver.ResolvedNav.all_files",
"signature": "<bound method Function.signature of Function('all_files', 43, 56)>",
"docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects."
"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."
}
}
},
@@ -297,8 +297,8 @@
"name": "resolve_nav",
"kind": "function",
"path": "docforge.nav.resolver.resolve_nav",
"signature": "<bound method Function.signature of Function('resolve_nav', 59, 124)>",
"docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n spec: The navigation specification to resolve.\n docs_root: The root directory for documentation files.\n\nReturns:\n A ResolvedNav instance.\n\nRaises:\n FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist."
"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",
@@ -314,7 +314,7 @@
"kind": "module",
"path": "docforge.nav.spec",
"signature": null,
"docstring": "This module defines the NavSpec class, which represents the user's intent for\ndocumentation navigation as defined in a YAML specification (usually\ndocforge.nav.yml).",
"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",
@@ -355,8 +355,8 @@
"name": "NavSpec",
"kind": "class",
"path": "docforge.nav.spec.NavSpec",
"signature": "<bound method Class.signature of Class('NavSpec', 13, 91)>",
"docstring": "Parsed representation of the docforge navigation specification file.\n\nAttributes:\n home: Path to the home document (e.g., 'index.md').\n groups: Mapping of group titles to lists of path patterns/globs.",
"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",
@@ -376,15 +376,15 @@
"name": "load",
"kind": "function",
"path": "docforge.nav.spec.NavSpec.load",
"signature": "<bound method Function.signature of Function('load', 37, 77)>",
"docstring": "Load a NavSpec from a YAML file.\n\nArgs:\n path: The filesystem path to the YAML file.\n\nReturns:\n A NavSpec instance.\n\nRaises:\n FileNotFoundError: If the path does not exist.\n ValueError: If the file content is not a valid NavSpec mapping."
"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', 79, 91)>",
"docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)."
"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."
}
}
},
@@ -392,8 +392,8 @@
"name": "load_nav_spec",
"kind": "function",
"path": "docforge.nav.spec.load_nav_spec",
"signature": "<bound method Function.signature of Function('load_nav_spec', 94, 114)>",
"docstring": "Utility function to load a NavSpec from a file.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A loaded NavSpec instance."
"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."
}
}
}