Commands

docforge.cli.commands

Summary

Command definitions for the doc-forge CLI.

Provides the CLI structure using Click, including build, serve, and tree commands.

Notes

The build command validates requested modes before generating anything.
--mkdocs, --api, and --wiki each emit their own MkDocs config and build (docs/mkdocs.{kind}.yml into site/{kind}); --mcp generates a machine-readable bundle independently.

Classes

Functions

build

build(
    mcp: bool,
    mkdocs: bool,
    api: bool,
    wiki: bool,
    refresh: bool,
    module_is_source: bool,
    module: str | None,
    openapi_spec: Path | None,
    project_name: str | None,
    site_name: str | None,
    docs_dir: Path,
    wiki_dir: Path,
    nav_file: Path,
    template: Path | None,
    out_dir: Path,
) -> None

Build documentation artifacts.

This command runs the full documentation pipeline: it loads Python modules, generates renderer-specific documentation sources, and optionally builds the final output.

Depending on the selected options, the build can target:

A lib MkDocs site (--mkdocs) for library reference docs
A swagger-enabled API MkDocs site (--api) built from an OpenAPI spec
A wiki MkDocs site (--wiki) built from hand-written markdown
MCP structured documentation resources (--mcp)

Each enabled site kind produces its own MkDocs configuration (docs/mkdocs.{kind}.yml) and its own build (site/{kind}).

Notes

At least one of --mcp, --mkdocs, --wiki, or --api must be provided.
--mkdocs, --api, and --wiki emit independent MkDocs builds, while --mcp emits a machine-readable bundle.
Configuration files are generated only when absent; an existing docs/mkdocs.{kind}.yml is used as-is. Pass --refresh to rebaseline it from the templates.

Parameters:

Name	Type	Description	Default
`mcp`	`bool`	Enable MCP documentation generation.	required
`mkdocs`	`bool`	Enable the lib MkDocs documentation generation.	required
`api`	`bool`	Enable API documentation generation from an OpenAPI spec.	required
`wiki`	`bool`	Build a hand-written wiki directory as its own MkDocs site.	required
`refresh`	`bool`	Regenerate `docs/mkdocs.{kind}.yml` from templates even when it already exists. By default, existing configs are used as-is.	required
`module_is_source`	`bool`	Treat the specified module directory as the project root.	required
`module`	`str \| None`	Python module import path to document.	required
`openapi_spec`	`Path \| None`	Path to the OpenAPI JSON specification used for API docs.	required
`project_name`	`str \| None`	Optional override for the project name.	required
`site_name`	`str \| None`	Display name for the lib and wiki MkDocs sites.	required
`docs_dir`	`Path`	Shared documentation root used for generated sources.	required
`wiki_dir`	`Path`	Directory containing hand-written wiki markdown files.	required
`nav_file`	`Path`	Path to the navigation specification file.	required
`template`	`Path \| None`	Optional custom MkDocs configuration template.	required
`out_dir`	`Path`	Output directory for generated MCP resources.	required

Raises:

Type	Description
`UsageError`	If required options are missing or conflicting.

serve

serve(
    mcp: bool,
    mkdocs: bool,
    lib: bool,
    api: bool,
    wiki: bool,
    module: str | None,
    mkdocs_yml: Path,
    out_dir: Path,
) -> None

Serve generated documentation locally.

Depending on the selected mode, this command starts either:

A MkDocs development server for browsing a site, or
An MCP server exposing structured documentation resources

The kind flags (--lib, --api, --wiki) select the generated per-kind config (docs/mkdocs.{kind}.yml); --mkdocs serves the config passed via --mkdocs-yml.

Parameters:

Name	Type	Description	Default
`mcp`	`bool`	Serve documentation using the MCP server.	required
`mkdocs`	`bool`	Serve the MkDocs development site from `--mkdocs-yml`.	required
`lib`	`bool`	Serve the lib MkDocs site.	required
`api`	`bool`	Serve the API MkDocs site.	required
`wiki`	`bool`	Serve the wiki MkDocs site.	required
`module`	`str \| None`	Python module import path to serve via MCP.	required
`mkdocs_yml`	`Path`	Path to the MkDocs configuration file.	required
`out_dir`	`Path`	Root directory containing MCP documentation resources.	required

Raises:

Type	Description
`UsageError`	If invalid or conflicting options are provided.

tree

tree(module: str, project_name: str | None) -> None

Display the documentation object tree for a module.

This command introspects the specified module and prints a hierarchical representation of the discovered documentation objects, including modules, classes, functions, and members.

Parameters:

Name	Type	Description	Default
`module`	`str`	Python module import path to introspect.	required
`project_name`	`str \| None`	Optional name to display as the project root.	required