Skip to content

# Spec

## `` docforge.nav.spec

Navigation specification model.

This module defines the `NavSpec` class, which represents the navigation structure defined by the user in the doc-forge navigation specification (typically `docforge.nav.yml`).

### Classes

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

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