doc-forge/docforge/cli/commands.py

import click
from pathlib import Path
from typing import Sequence, Optional
from docforge.loaders import GriffeLoader
from docforge.cli import mkdocs_utils
from docforge.cli import mcp_utils


@click.group()
def cli() -> None:
    """
    doc-forge CLI: A tool for introspecting Python projects and generating
    documentation.
    """
    pass


@cli.command()
@click.option("--mcp", is_flag=True, help="Build MCP resources")
@click.option("--mkdocs", is_flag=True, help="Build MkDocs site")
@click.option("--module-is-source", is_flag=True, help="Module is source folder and to be treated as root folder")
@click.option("--module", help="Python module to document")
@click.option("--project-name", help="Project name override")
# MkDocs specific
@click.option("--site-name", help="MkDocs site name")
@click.option("--docs-dir", type=click.Path(path_type=Path), default=Path("docs"), help="Directory for MD sources")
@click.option("--nav", "nav_file", type=click.Path(path_type=Path), default=Path("docforge.nav.yml"),
              help="Nav spec path")
@click.option("--template", type=click.Path(path_type=Path), help="MkDocs template path")
@click.option("--mkdocs-yml", type=click.Path(path_type=Path), default=Path("mkdocs.yml"), help="Output config path")
# MCP specific
@click.option("--out-dir", type=click.Path(path_type=Path), default=Path("mcp_docs"), help="MCP output directory")
def build(
    mcp: bool,
    mkdocs: bool,
    module_is_source: bool,
    module: Optional[str],
    project_name: Optional[str],
    site_name: Optional[str],
    docs_dir: Path,
    nav_file: Path,
    template: Optional[Path],
    mkdocs_yml: Path,
    out_dir: Path,
) -> None:
    """
    Build documentation (MkDocs site or MCP resources).

    This command orchestrates the full build process:
    1. Introspects the code (Griffe)
    2. Renders sources (MkDocs Markdown or MCP JSON)
    3. (MkDocs only) Generates config and runs the final site build.

    Args:
        mcp: Use the MCP documentation builder.
        mkdocs: Use the MkDocs documentation builder.
        module_is_source: Module is the source folder and to be treated as the root folder.
        module: The dotted path of the module to the document.
        project_name: Optional override for the project name.
        site_name: (MkDocs) The site display name. Defaults to module name.
        docs_dir: (MkDocs) Target directory for Markdown sources.
        nav_file: (MkDocs) Path to the docforge.nav.yml specification.
        template: (MkDocs) Optional custom mkdocs.yml template.
        mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.
        out_dir: (MCP) Target directory for MCP JSON resources.
    """
    if not mcp and not mkdocs:
        raise click.UsageError("Must specify either --mcp or --mkdocs")

    if mkdocs:
        if not module:
            raise click.UsageError("--module is required for MkDocs build")
        if not site_name:
            site_name = module

        click.echo(f"Generating MkDocs sources in {docs_dir}...")
        mkdocs_utils.generate_sources(
            module,
            docs_dir,
            project_name,
            module_is_source,
        )

        click.echo(f"Generating MkDocs config {mkdocs_yml}...")
        mkdocs_utils.generate_config(docs_dir, nav_file, template, mkdocs_yml, site_name)

        click.echo("Running MkDocs build...")
        mkdocs_utils.build(mkdocs_yml)
        click.echo("MkDocs build completed.")

    if mcp:
        if not module:
            raise click.UsageError("--module is required for MCP build")

        click.echo(f"Generating MCP resources in {out_dir}...")
        mcp_utils.generate_resources(module, project_name, out_dir)
        click.echo("MCP build completed.")


@cli.command()
@click.option("--mcp", is_flag=True, help="Serve MCP documentation")
@click.option("--mkdocs", is_flag=True, help="Serve MkDocs site")
@click.option("--module", help="Python module to serve")
@click.option("--mkdocs-yml", type=click.Path(path_type=Path), default=Path("mkdocs.yml"), help="MkDocs config path")
@click.option("--out-dir", type=click.Path(path_type=Path), default=Path("mcp_docs"), help="MCP root directory")
def serve(
    mcp: bool,
    mkdocs: bool,
    module: Optional[str],
    mkdocs_yml: Path,
    out_dir: Path,
) -> None:
    """
    Serve documentation (MkDocs or MCP).

    Args:
        mcp: Serve MCP resources via an MCP server.
        mkdocs: Serve the MkDocs site using the built-in development server.
        module: The dotted path of the module to serve.
        mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.
        out_dir: (MCP) Path to the mcp_docs/ directory.
    """
    if mcp and mkdocs:
        raise click.UsageError("Cannot specify both --mcp and --mkdocs")
    if not mcp and not mkdocs:
        raise click.UsageError("Must specify either --mcp or --mkdocs")
    if mcp and not module:
        raise click.UsageError("--module is required for MCP serve")

    if mkdocs:
        mkdocs_utils.serve(mkdocs_yml)
    elif mcp:
        mcp_utils.serve(module, out_dir)


@cli.command()
@click.option(
    "--module",
    required=True,
    help="Python module import path to introspect",
)
@click.option(
    "--project-name",
    help="Project name (defaults to specified module)",
)
def tree(
    module: str,
    project_name: Optional[str],
) -> None:
    """
    Visualize the project structure in the terminal.

    Args:
        module: The module import path to recursively introspect.
        project_name: Optional override for the project name shown at the root.
    """
    loader = GriffeLoader()
    project = loader.load_project([module], project_name)

    click.echo(project.name)

    for module in project.get_all_modules():
        click.echo(f"├── {module.path}")
        for obj in module.get_all_objects():
            _print_object(obj, indent="│   ")


def _print_object(obj, indent: str) -> None:
    """
    Recursive helper to print doc objects and their members to the console.

    Args:
        obj: The DocObject instance to print.
        indent: Current line indentation (e.g., '│   ').
    """
    click.echo(f"{indent}├── {obj.name}")
    for member in obj.get_all_members():
        _print_object(member, indent + "│   ")