Skip to content

# Mkdocs Utils

## `` docforge.cli.mkdocs_utils

### Summary

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

### Classes

### Functions

#### `` build

    1

    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

    1

    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

    1

    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

    1

    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.