Mkdocs Utils

docforge.cli.mkdocs_utils

Summary

Utilities for working with MkDocs in the doc-forge CLI.

---

Notes

• A separate mkdocs.{kind}.yml configuration and build is emitted per enabled kind (lib, api, wiki), each scoped to its own docs_dir and written into its own site_dir (site/lib, site/api, site/wiki).
• Navigation blocks are re-rooted per kind: the wiki navigation drops its leading wiki/ scope and the resolved nav spec drops its lib/ scope.

---

Classes

Functions

build_configs

build_configs(yml_paths: Iterable[Path]) -> None

Build the MkDocs documentation site for every given configuration.

Each configuration file is loaded and built in turn, producing the per-kind static sites (site/lib, site/api, site/wiki).

Parameters:

Name	Type	Description	Default
yml_paths	Iterable[Path]	Configuration files to build, in order.	required

Raises:

Type	Description
ClickException	If a configuration file does not exist.

build_lib_nav

build_lib_nav(
    nav_file: Path, docs_root: Path
) -> tuple[list[dict[str, Any]], dict[str, str] | None]

Build the re-rooted navigation block for a lib site.

The navigation specification is resolved against the shared documentation root and every resulting path is re-rooted relative to the lib subdirectory by stripping its leading lib/ scope component.

Parameters:

Name	Type	Description	Default
nav_file	Path	Path to the docforge.nav.yml navigation specification.	required
docs_root	Path	Shared documentation root containing the lib sources.	required

Returns:

Type	Description
tuple[list[dict[str, Any]], dict[str, str] | None]	tuple[list[dict[str, Any]], dict[str, str] | None]: The re-rooted navigation block and the optional theme icon mapping from the specification.

Raises:

Type	Description
FileError	If the navigation specification cannot be found.

build_wiki_nav_block

build_wiki_nav_block(
    wiki_dir: Path,
) -> list[dict[str, Any]]

Build the re-rooted navigation block for a wiki site.

The wiki navigation derived from the wiki file structure is re-rooted relative to the wiki directory itself by stripping the leading wiki/ scope component.

Parameters:

Name	Type	Description	Default
wiki_dir	Path	Path to the hand-written wiki directory, for example docs/wiki.	required

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: Navigation entries relative to the wiki directory.

Raises:

Type	Description
FileError	If the wiki directory does not exist.

generate_site_config

generate_site_config(
    kind: str,
    kind_root: Path,
    nav_block: list[dict[str, Any]],
    out: Path,
    site_name: str,
    docs_dir: str,
    site_dir: str,
    template: Path | None = None,
    site_description: str | None = None,
    site_author: str | None = None,
    theme_icon: dict[str, str] | None = None,
) -> None

Generate a per-kind mkdocs.{kind}.yml configuration file.

The configuration is created by merging the shared mkdocs.common.yml template with the fragment contributed by the kind (lib, api, or wiki). Both docs_dir and site_dir are written relative to the configuration file's directory: the kind's sources when expressed as a sibling path (for example lib) and the per-kind site output (for example ../site/lib).

Parameters:

Name	Type	Description	Default
kind	str	Documentation kind, one of lib, api, or wiki.	required
kind_root	Path	Directory scoped to the kind (for example docs/lib) that serves as the MkDocs docs_dir.	required
nav_block	list[dict[str, Any]]	Re-rooted navigation entries for the kind's site.	required
out	Path	Destination path where the generated mkdocs.{kind}.yml file is written.	required
site_name	str	Display name for the generated documentation site.	required
docs_dir	str	MkDocs docs_dir value, relative to the configuration file's directory.	required
site_dir	str	MkDocs site_dir value, relative to the configuration file's directory.	required
template	Path | None	Optional path to a fully custom MkDocs configuration template that replaces the built-in templates entirely.	None
site_description	str | None	Optional site description written into the configuration.	None
site_author	str | None	Optional site author written into the configuration.	None
theme_icon	dict[str, str] | None	Optional mapping of theme icon entries injected as theme.icon.	None

generate_sources

generate_sources(
    module: str,
    docs_dir: Path,
    project_name: str | None = None,
    module_is_source: bool | None = None,
    readme_dir: Path | None = None,
) -> None

Generate MkDocs Markdown sources for a Python module.

This function introspects the specified module, builds the internal documentation model, and renders Markdown documentation files for use with MkDocs.

Parameters:

Name	Type	Description	Default
module	str	Python module import path used as the entry point for documentation generation.	required
docs_dir	Path	Directory where the generated Markdown files will be written.	required
project_name	str | None	Optional override for the project name used in documentation metadata.	None
module_is_source	bool | None	If True, treat the specified module directory as the project root rather than a nested module.	None
readme_dir	Path | None	Directory where the generated README.md should be written. If not provided, defaults to the parent of docs_dir.	None

load_spec_icon

load_spec_icon(nav_file: Path) -> dict[str, str] | None

Load the theme icon mapping from a navigation specification.

Parameters:

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

Returns:

Type	Description
dict[str, str] | None	dict[str, str] | None: The icon mapping, or None when the specification file is absent or cannot be parsed.

serve

serve(mkdocs_yml: Path) -> None

Start an MkDocs development server with live reload.

The server watches documentation files and automatically reloads the site when changes are detected.

Parameters:

Name	Type	Description	Default
mkdocs_yml	Path	Path to the mkdocs.yml configuration file.	required

Raises:

Type	Description
ClickException	If the configuration file does not exist.