Spec

docforge.nav.spec

This module defines the NavSpec class, which represents the user's intent for documentation navigation as defined in a YAML specification (usually docforge.nav.yml).

NavSpec

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

Parsed representation of the docforge navigation specification file.

Attributes:

Name	Type	Description
home	Optional[str]	Path to the home document (e.g., 'index.md').
groups	Dict[str, List[str]]	Mapping of group titles to lists of path patterns/globs.

Initialize a NavSpec.

Parameters:

Name	Type	Description	Default
home	Optional[str]	The path to the home document.	required
groups	Dict[str, List[str]]	A mapping of group names to lists of path patterns (globs).	required

all_patterns

all_patterns() -> List[str]

Get all path patterns referenced in the specification.

Returns:

Type	Description
List[str]	A list of all patterns (home plus all groups).

load classmethod

load(path: Path) -> NavSpec

Load a NavSpec from a YAML file.

Parameters:

Name	Type	Description	Default
path	Path	The filesystem path to the YAML file.	required

Returns:

Type	Description
NavSpec	A NavSpec instance.

Raises:

Type	Description
FileNotFoundError	If the path does not exist.
ValueError	If the file content is not a valid NavSpec mapping.

load_nav_spec

load_nav_spec(path: Path) -> NavSpec

Utility function to load a NavSpec from a file.

Parameters:

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

Returns:

Type	Description
NavSpec	A loaded NavSpec instance.