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

---

Notes

• The spec file supports an optional icon mapping for MkDocs theme customization.
• All file references in groups are relative to the documentation root.

---

Classes

NavSpec

NavSpec(
    home: str | None,
    groups: dict[str, list[str]],
    icon: dict[str, str] | None = None,
)

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	str | None	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.
icon		Optional mapping of theme icon entries (for example {"logo": "material/code-tags"}) injected into the MkDocs theme as theme.icon.

Initialize a NavSpec instance.

Parameters:

Name	Type	Description	Default
home	str | None	Relative path to the home document.	required
groups	dict[str, list[str]]	Mapping of group names to lists of path patterns (glob expressions).	required
icon	dict[str, str] | None	Optional mapping of theme icon entries applied to the generated MkDocs configuration.	None

Functions

all_patterns

all_patterns() -> list[str]

Return all path patterns referenced by the specification.

Returns:

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

load classmethod

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:

Name	Type	Description
NavSpec	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

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:

Name	Type	Description
NavSpec	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.