Nav

docforge.nav

Navigation Layer

The docforge.nav package manages the mapping between the logical documentation structure and the physical files on disk.

Workflow

1. Spec Definition: Users define navigation intent in docforge.nav.yml.
2. Resolution: resolve_nav matches patterns in the spec to generated .md files.
3. Emission: MkDocsNavEmitter produces the final YAML structure for mkdocs.yml.

This abstraction allows doc-forge to support complex grouping and ordering independently of the source code's physical layout.

MkDocsNavEmitter

Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible navigation structure.

emit

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

Generate a list of navigation entries for mkdocs.yml.

Parameters:

Name	Type	Description	Default
nav	ResolvedNav	The resolved navigation data.	required

Returns:

Type	Description
List[Dict[str, Any]]	A list of dictionary mappings representing the MkDocs navigation.

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.

ResolvedNav

ResolvedNav(home: str | None, groups: Dict[str, List[Path]], docs_root: Path | None = None)

Represents a navigation structure where all patterns and paths have been resolved against the actual filesystem contents.

Attributes:

Name	Type	Description
home	Optional[str]	Resolved relative path to the home page.
groups	Dict[str, List[Path]]	Mapping of group titles to lists of absolute or relative Path objects.

Initialize a ResolvedNav instance.

Parameters:

Name	Type	Description	Default
home	str | None	The relative path to the project home page.	required
groups	Dict[str, List[Path]]	A mapping of group names to their resolved filesystem paths.	required
docs_root	Path | None	The root documentation directory.	None

all_files

all_files() -> Iterable[Path]

Get an iterable of all resolved files in the navigation structure.

Returns:

Type	Description
Iterable[Path]	An iterable of Path objects.

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.

resolve_nav

resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav

Create a ResolvedNav by processing a NavSpec against the filesystem. This expands globs and validates the existence of referenced files.

Parameters:

Name	Type	Description	Default
spec	NavSpec	The navigation specification to resolve.	required
docs_root	Path	The root directory for documentation files.	required

Returns:

Type	Description
ResolvedNav	A ResolvedNav instance.

Raises:

Type	Description
FileNotFoundError	If a pattern doesn't match any files or the docs_root doesn't exist.