Resolver

docforge.nav.resolver

Navigation resolution utilities.

This module resolves a NavSpec against the filesystem by expanding glob patterns and validating that referenced documentation files exist.

ResolvedNav(home: str | None, groups: Dict[str, List[Path]], docs_root: Path | None = None)

Resolved navigation structure.

A ResolvedNav represents navigation data after glob patterns have been expanded and paths validated against the filesystem.

Attributes:

Name	Type	Description
`home`	`Optional[str]`	Relative path to the documentation home page.
`groups`	`Dict[str, List[Path]]`	Mapping of navigation group titles to lists of resolved documentation file paths.

Initialize a ResolvedNav instance.

Parameters:

Name	Type	Description	Default
`home`	`str \| None`	Relative path to the home page within the documentation root.	required
`groups`	`Dict[str, List[Path]]`	Mapping of group titles to resolved documentation file paths.	required
`docs_root`	`Path \| None`	Root directory of the documentation source files.	`None`

all_files() -> Iterable[Path]

Iterate over all files referenced by the navigation structure.

Returns:

Type	Description
`Iterable[Path]`	An iterable of `Path` objects representing documentation files.

Raises:

Type	Description
`RuntimeError`	If the home page is defined but the documentation root is not available for resolution.

resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav

Resolve a navigation specification against the filesystem.

The function expands glob patterns defined in a NavSpec and verifies that referenced documentation files exist within the documentation root.

Parameters:

Name	Type	Description	Default
`spec`	`NavSpec`	Navigation specification describing documentation layout.	required
`docs_root`	`Path`	Root directory containing documentation Markdown files.	required

Returns:

Type	Description
`ResolvedNav`	A `ResolvedNav` instance containing validated navigation paths.

Raises:

Type	Description
`FileNotFoundError`	If the documentation root does not exist or a navigation pattern does not match any files.