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,
    modes: Iterable[str] | None = None,
    site_description: str | None = None,
    site_author: str | None = None,
    wiki_dir: Path | None = None,
) -> 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 (and, when a wiki directory is provided, from the wiki file structure).

The docs_dir is always written relative to the MkDocs root and is expected to be the shared documentation parent (for example docs), with generated sources nested under lib/ or api/ subdirectories and hand-written wiki content under a wiki/ subdirectory.

Parameters:

Name	Type	Description	Default
docs_dir	Path	Shared documentation root used as the MkDocs docs_dir.	required
nav_file	Path	Path to the docforge.nav.yml navigation specification.	required
template	Optional[Path]	Optional path to a fully custom MkDocs configuration template. If not provided, built-in templates are merged; the provided template replaces the built-in templates entirely.	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
modes	Optional[Iterable[str]]	Documentation modes to enable. Each mode contributes its own built-in template fragment (for example lib, api, or wiki), merged on top of the shared mkdocs.common.yml template.	None
site_description	Optional[str]	Optional site description written into the configuration.	None
site_author	Optional[str]	Optional site author written into the configuration.	None
wiki_dir	Optional[Path]	Optional path to a hand-written wiki directory (for example docs/wiki). When provided, the site navigation is derived from the wiki file structure and placed before the navigation groups defined in nav_file.	None

Raises:

Type	Description
FileError	If the navigation specification, template, or wiki directory cannot be found.

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	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
readme_dir	Optional[Path]	Directory where the generated README.md should be written. If not provided, defaults to the parent of docs_dir.	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.