Skip to content

# 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.

### Classes

#### `` ResolvedNav

    1

    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`

##### Functions

###### `` all_files

    1

    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.

### Functions

#### `` resolve_nav

    1

    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.