Mkdocs Utils

docforge.cli.mkdocs_utils

Summary

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

Classes

Functions

build

build(mkdocs_yml: Path) -> None

Build the MkDocs documentation site.

This function loads the MkDocs configuration and runs the MkDocs build command to generate the final static documentation site.

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.

generate_config

generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None

Generate an mkdocs.yml configuration file.

The configuration is created by combining a template configuration with a navigation structure derived from the docforge navigation specification.

Parameters:

Name	Type	Description	Default
docs_dir	Path	Directory containing generated documentation Markdown files.	required
nav_file	Path	Path to the docforge.nav.yml navigation specification.	required
template	Optional[Path]	Optional path to a custom MkDocs configuration template. If not provided, a built-in template will be used.	required
out	Path	Destination path where the generated mkdocs.yml file will be written.	required
site_name	str	Display name for the generated documentation site.	required

Raises:

Type	Description
FileError	If the navigation specification or template file cannot be found.

generate_sources

generate_sources(module: str, docs_dir: Path, project_name: str | None = None, module_is_source: bool | 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	Optional[str]	Optional override for the project name used in documentation metadata.	None
module_is_source	Optional[bool]	If True, treat the specified module directory as the project root rather than a nested module.	None

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.