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

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

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

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

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.