341 lines
24 KiB
JSON
341 lines
24 KiB
JSON
{
|
||
"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": "NavSpec(home: str | None, groups: dict[str, list[str]], icon: dict[str, str] | None = None)",
|
||
"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.\n icon: Optional mapping of theme icon entries (for example\n ``{\"logo\": \"material/code-tags\"}``) injected into the MkDocs\n theme as ``theme.icon``.",
|
||
"members": {
|
||
"home": {
|
||
"name": "home",
|
||
"kind": "attribute",
|
||
"path": "docforge.nav.NavSpec.home",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"groups": {
|
||
"name": "groups",
|
||
"kind": "attribute",
|
||
"path": "docforge.nav.NavSpec.groups",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"icon": {
|
||
"name": "icon",
|
||
"kind": "attribute",
|
||
"path": "docforge.nav.NavSpec.icon",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"load": {
|
||
"name": "load",
|
||
"kind": "function",
|
||
"path": "docforge.nav.NavSpec.load",
|
||
"signature": "load(path: Path)",
|
||
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path (Path):\n Filesystem path to the navigation specification file.\n\nReturns:\n NavSpec:\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": "all_patterns()",
|
||
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n list[str]:\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": "load_nav_spec(path: Path)",
|
||
"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):\n Path to the navigation specification file.\n\nReturns:\n NavSpec:\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": "ResolvedNav(home: str | None, groups: dict[str, list[Path]], docs_root: Path | None = None)",
|
||
"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": null,
|
||
"docstring": null
|
||
},
|
||
"groups": {
|
||
"name": "groups",
|
||
"kind": "attribute",
|
||
"path": "docforge.nav.ResolvedNav.groups",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"all_files": {
|
||
"name": "all_files",
|
||
"kind": "function",
|
||
"path": "docforge.nav.ResolvedNav.all_files",
|
||
"signature": "all_files()",
|
||
"docstring": "Iterate over all files referenced by the navigation structure.\n\nYields:\n Path:\n A documentation file referenced by the navigation, including\n the home page when defined.\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": "resolve_nav(spec: NavSpec, docs_root: Path)",
|
||
"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 (NavSpec):\n Navigation specification describing documentation layout.\n docs_root (Path):\n Root directory containing documentation Markdown files.\n\nReturns:\n ResolvedNav:\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": null,
|
||
"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": "emit(nav: ResolvedNav)",
|
||
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav (ResolvedNav):\n Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n list[dict[str, Any]]:\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."
|
||
}
|
||
}
|
||
},
|
||
"build_wiki_nav": {
|
||
"name": "build_wiki_nav",
|
||
"kind": "function",
|
||
"path": "docforge.nav.build_wiki_nav",
|
||
"signature": "build_wiki_nav(wiki_dir: Path)",
|
||
"docstring": "Derive an MkDocs navigation block from a wiki directory.\n\nReturned paths are relative to the parent of ``wiki_dir`` and carry the\nwiki directory name as their leading component (for example\n``wiki/01_overview.md`` when the wiki lives at ``docs/wiki``). This makes\nthe result directly usable in an MkDocs ``nav`` block with\n\n- ``index.md`` at the wiki root becomes the ``Home`` entry.\n- Page labels are derived from filenames: numeric order prefixes such as\n ``01_`` or ``02-`` are stripped, separators are replaced with spaces, and\n names are title-cased (``01_overview.md`` becomes ``Overview``).\n- Subdirectories become nested navigation groups. A nested ``index.md`` is\n rendered as the section root placed first inside the group.\n- Only ``.md`` files are considered; hidden entries are ignored.\n\nArgs:\n wiki_dir (Path):\n Path to the hand-written wiki directory, for example ``docs/wiki``.\n\nReturns:\n list[dict[str, Any]]:\n Navigation entries compatible with the MkDocs ``nav`` configuration.\n The list is empty if the wiki contains no Markdown files.\n\nRaises:\n FileNotFoundError:\n If the wiki directory does not exist."
|
||
},
|
||
"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.\n\n---\n\nNotes:\n - The emitted structure is a list of dictionaries, one per top-level nav\n entry, matching the MkDocs ``nav`` YAML format.\n\n---",
|
||
"members": {
|
||
"ResolvedNav": {
|
||
"name": "ResolvedNav",
|
||
"kind": "class",
|
||
"path": "docforge.nav.mkdocs.ResolvedNav",
|
||
"signature": "ResolvedNav(home: str | None, groups: dict[str, list[Path]], docs_root: Path | None = None)",
|
||
"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": null,
|
||
"docstring": null
|
||
},
|
||
"groups": {
|
||
"name": "groups",
|
||
"kind": "attribute",
|
||
"path": "docforge.nav.mkdocs.ResolvedNav.groups",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"all_files": {
|
||
"name": "all_files",
|
||
"kind": "function",
|
||
"path": "docforge.nav.mkdocs.ResolvedNav.all_files",
|
||
"signature": "all_files()",
|
||
"docstring": "Iterate over all files referenced by the navigation structure.\n\nYields:\n Path:\n A documentation file referenced by the navigation, including\n the home page when defined.\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": null,
|
||
"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": "emit(nav: ResolvedNav) -> list[dict[str, Any]]",
|
||
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav (ResolvedNav):\n Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n list[dict[str, Any]]:\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.\n\n---\n\nNotes:\n - Glob resolution is recursive and returns paths in sorted order.\n - Unmatched patterns raise ``FileNotFoundError`` to fail fast on typos.\n\n---",
|
||
"members": {
|
||
"NavSpec": {
|
||
"name": "NavSpec",
|
||
"kind": "class",
|
||
"path": "docforge.nav.resolver.NavSpec",
|
||
"signature": "NavSpec(home: str | None, groups: dict[str, list[str]], icon: dict[str, str] | None = None)",
|
||
"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.\n icon: Optional mapping of theme icon entries (for example\n ``{\"logo\": \"material/code-tags\"}``) injected into the MkDocs\n theme as ``theme.icon``.",
|
||
"members": {
|
||
"home": {
|
||
"name": "home",
|
||
"kind": "attribute",
|
||
"path": "docforge.nav.resolver.NavSpec.home",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"groups": {
|
||
"name": "groups",
|
||
"kind": "attribute",
|
||
"path": "docforge.nav.resolver.NavSpec.groups",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"icon": {
|
||
"name": "icon",
|
||
"kind": "attribute",
|
||
"path": "docforge.nav.resolver.NavSpec.icon",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"load": {
|
||
"name": "load",
|
||
"kind": "function",
|
||
"path": "docforge.nav.resolver.NavSpec.load",
|
||
"signature": "load(path: Path)",
|
||
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path (Path):\n Filesystem path to the navigation specification file.\n\nReturns:\n NavSpec:\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": "all_patterns()",
|
||
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n list[str]:\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": "ResolvedNav(home: str | None, groups: dict[str, list[Path]], docs_root: Path | None = None)",
|
||
"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": "all_files() -> Iterable[Path]",
|
||
"docstring": "Iterate over all files referenced by the navigation structure.\n\nYields:\n Path:\n A documentation file referenced by the navigation, including\n the home page when defined.\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": "resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav",
|
||
"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 (NavSpec):\n Navigation specification describing documentation layout.\n docs_root (Path):\n Root directory containing documentation Markdown files.\n\nReturns:\n ResolvedNav:\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."
|
||
}
|
||
}
|
||
},
|
||
"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``).\n\n---\n\nNotes:\n - The spec file supports an optional ``icon`` mapping for MkDocs theme\n customization.\n - All file references in ``groups`` are relative to the documentation root.\n\n---",
|
||
"members": {
|
||
"NavSpec": {
|
||
"name": "NavSpec",
|
||
"kind": "class",
|
||
"path": "docforge.nav.spec.NavSpec",
|
||
"signature": "NavSpec(home: str | None, groups: dict[str, list[str]], icon: dict[str, str] | None = None)",
|
||
"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.\n icon: Optional mapping of theme icon entries (for example\n ``{\"logo\": \"material/code-tags\"}``) injected into the MkDocs\n theme as ``theme.icon``.",
|
||
"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
|
||
},
|
||
"icon": {
|
||
"name": "icon",
|
||
"kind": "attribute",
|
||
"path": "docforge.nav.spec.NavSpec.icon",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"load": {
|
||
"name": "load",
|
||
"kind": "function",
|
||
"path": "docforge.nav.spec.NavSpec.load",
|
||
"signature": "load(path: Path) -> NavSpec",
|
||
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path (Path):\n Filesystem path to the navigation specification file.\n\nReturns:\n NavSpec:\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": "all_patterns() -> list[str]",
|
||
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n list[str]:\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": "load_nav_spec(path: Path) -> NavSpec",
|
||
"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):\n Path to the navigation specification file.\n\nReturns:\n NavSpec:\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."
|
||
}
|
||
}
|
||
},
|
||
"wiki": {
|
||
"name": "wiki",
|
||
"kind": "module",
|
||
"path": "docforge.nav.wiki",
|
||
"signature": null,
|
||
"docstring": "# Summary\n\nWiki navigation derivation.\n\nThis module provides ``build_wiki_nav``, which derives an MkDocs-ready\nnavigation block from the file structure of a hand-written wiki directory\n(typically ``docs/wiki``). wiki content is authored by hand and is never\nmodified by doc-forge; only the navigation layout is inferred.\n\n# Notes\n\n- ``index.md`` at the wiki root becomes the ``Home`` entry.\n- Page labels are derived from filenames: numeric order prefixes such as\n ``01_`` or ``02-`` are stripped, separators are replaced with spaces, and\n names are title-cased (``01_overview.md`` becomes ``Overview``).\n- Subdirectories become nested navigation groups. A nested ``index.md`` is\n rendered as the section root placed first inside the group.\n- Only ``.md`` files are considered; hidden entries are ignored.",
|
||
"members": {
|
||
"build_wiki_nav": {
|
||
"name": "build_wiki_nav",
|
||
"kind": "function",
|
||
"path": "docforge.nav.wiki.build_wiki_nav",
|
||
"signature": "build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]",
|
||
"docstring": "Derive an MkDocs navigation block from a wiki directory.\n\nReturned paths are relative to the parent of ``wiki_dir`` and carry the\nwiki directory name as their leading component (for example\n``wiki/01_overview.md`` when the wiki lives at ``docs/wiki``). This makes\nthe result directly usable in an MkDocs ``nav`` block with\n\n- ``index.md`` at the wiki root becomes the ``Home`` entry.\n- Page labels are derived from filenames: numeric order prefixes such as\n ``01_`` or ``02-`` are stripped, separators are replaced with spaces, and\n names are title-cased (``01_overview.md`` becomes ``Overview``).\n- Subdirectories become nested navigation groups. A nested ``index.md`` is\n rendered as the section root placed first inside the group.\n- Only ``.md`` files are considered; hidden entries are ignored.\n\nArgs:\n wiki_dir (Path):\n Path to the hand-written wiki directory, for example ``docs/wiki``.\n\nReturns:\n list[dict[str, Any]]:\n Navigation entries compatible with the MkDocs ``nav`` configuration.\n The list is empty if the wiki contains no Markdown files.\n\nRaises:\n FileNotFoundError:\n If the wiki directory does not exist."
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
} |