Skip to content

Nav

docforge.nav

Navigation layer for doc-forge.

The docforge.nav package manages the relationship between the logical documentation structure defined by the user and the physical documentation files generated on disk.

Workflow

  1. Specification – Users define navigation intent in docforge.nav.yml.
  2. Resolution – resolve_nav expands patterns and matches them against generated Markdown files.
  3. Emission – MkDocsNavEmitter converts the resolved structure into the YAML navigation format required by mkdocs.yml.

This layer separates documentation organization from the underlying source code layout, enabling flexible grouping, ordering, and navigation structures independent of module hierarchy.

Classes

MkDocsNavEmitter

Emit MkDocs navigation structures from resolved navigation data.

The emitter transforms a ResolvedNav object into the YAML-compatible list structure expected by the MkDocs nav configuration field.

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

Generate a navigation structure for mkdocs.yml.

Parameters:

Name Type Description Default
nav ResolvedNav

Resolved navigation data describing documentation groups and their associated Markdown files.

 required

Returns:

Type Description
List[Dict[str, Any]]

A list of dictionaries representing the MkDocs navigation layout.
List[Dict[str, Any]]

Each dictionary maps a navigation label to a page or a list of
List[Dict[str, Any]]

pages.

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.

ResolvedNav 

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

Resolved navigation structure.

A ResolvedNav represents navigation data after glob patterns have been expanded and paths validated against the filesystem.

Attributes:

Name Type Description
home Optional[str]

Relative path to the documentation home page.
groups Dict[str, List[Path]]

Mapping of navigation group titles to lists of resolved documentation file paths.

Initialize a ResolvedNav instance.

Parameters:

Name Type Description Default
home str | None

Relative path to the home page within the documentation root.

 required
groups Dict[str, List[Path]]

Mapping of group titles to resolved documentation file paths.

 required
docs_root Path | None

Root directory of the documentation source files.

 None
Functions
all_files 
1
all_files() -> Iterable[Path]

Iterate over all files referenced by the navigation structure.

Returns:

Type Description
Iterable[Path]

An iterable of Path objects representing documentation files.

Raises:

Type Description
RuntimeError

If the home page is defined but the documentation root is not available for resolution.

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.

resolve_nav 

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

Resolve a navigation specification against the filesystem.

The function expands glob patterns defined in a NavSpec and verifies that referenced documentation files exist within the documentation root.

Parameters:

Name Type Description Default
spec NavSpec

Navigation specification describing documentation layout.

 required
docs_root Path

Root directory containing documentation Markdown files.

 required

Returns:

Type Description
ResolvedNav

A ResolvedNav instance containing validated navigation paths.

Raises:

Type Description
FileNotFoundError

If the documentation root does not exist or a navigation pattern does not match any files.