Mkdocs Utils

docforge.cli.mkdocs_utils

Summary

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

Notes

A single generated mkdocs.yml serves lib, api, and wiki content with merged navigation. Wiki navigation, when enabled, precedes every other group and its index.md becomes the site Home.

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`	`Path \| None`	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`	`Iterable[str] \| None`	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`	`str \| None`	Optional site description written into the configuration.	`None`
`site_author`	`str \| None`	Optional site author written into the configuration.	`None`
`wiki_dir`	`Path \| None`	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`	`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`

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.