Skip to content

# Nav

## `` docforge.nav

Navigation layer for doc-forge.

The `docforge.nav` package manages the relationship between the logical documentation structure defined by the user and the physical documentation files generated on disk.

#### Workflow

1. Specification – Users define navigation intent in `docforge.nav.yml`.
2. Resolution – `resolve_nav` expands patterns and matches them against generated Markdown files.
3. Emission – `MkDocsNavEmitter` converts the resolved structure into the YAML navigation format required by `mkdocs.yml`.

This layer separates documentation organization from the underlying source code layout, enabling flexible grouping, ordering, and navigation structures independent of module hierarchy.

### Classes

#### `` MkDocsNavEmitter

Emit MkDocs navigation structures from resolved navigation data.

The emitter transforms a `ResolvedNav` object into the YAML-compatible list structure expected by the MkDocs `nav` configuration field.

##### Functions

###### `` emit

    1

    emit(nav: ResolvedNav) -> List[Dict[str, Any]]

Generate a navigation structure for `mkdocs.yml`.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`nav` | `ResolvedNav` | Resolved navigation data describing documentation groups and their associated Markdown files. | required

Returns:

Type | Description
--- | ---
`List[Dict[str, Any]]` | A list of dictionaries representing the MkDocs navigation layout.
`List[Dict[str, Any]]` | Each dictionary maps a navigation label to a page or a list of
`List[Dict[str, Any]]` | pages.

#### `` NavSpec

    1

    NavSpec(home: Optional[str], groups: Dict[str, List[str]])

Parsed representation of a navigation specification.

A `NavSpec` describes the intended documentation navigation layout before it is resolved against the filesystem.

Attributes:

Name | Type | Description
--- | --- | ---
`home` | `Optional[str]` | Relative path to the documentation home page (for example `index.md`).
`groups` | `Dict[str, List[str]]` | Mapping of navigation group titles to lists of file patterns or glob expressions.

Initialize a NavSpec instance.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`home` | `Optional[str]` | Relative path to the home document. | required
`groups` | `Dict[str, List[str]]` | Mapping of group names to lists of path patterns (glob expressions). | required

##### Functions

###### `` all_patterns

    1

    all_patterns() -> List[str]

Return all path patterns referenced by the specification.

Returns:

Type | Description
--- | ---
`List[str]` | A list containing the home document (if defined) and all
`List[str]` | group pattern entries.

###### `` load `classmethod`

    1

    load(path: Path) -> NavSpec

Load a navigation specification from a YAML file.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`path` | `Path` | Filesystem path to the navigation specification file. | required

Returns:

Type | Description
--- | ---
`NavSpec` | A `NavSpec` instance representing the parsed configuration.

Raises:

Type | Description
--- | ---
`FileNotFoundError` | If the specified file does not exist.
`ValueError` | If the file contents are not a valid navigation specification.

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

#### `` load_nav_spec

    1

    load_nav_spec(path: Path) -> NavSpec

Load a navigation specification file.

This helper function reads a YAML navigation file and constructs a corresponding `NavSpec` instance.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`path` | `Path` | Path to the navigation specification file. | required

Returns:

Type | Description
--- | ---
`NavSpec` | A `NavSpec` instance representing the parsed specification.

Raises:

Type | Description
--- | ---
`FileNotFoundError` | If the specification file does not exist.
`ValueError` | If the YAML structure is invalid.

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