288 lines
7.7 KiB
Python
288 lines
7.7 KiB
Python
"""
|
|
# Summary
|
|
|
|
Command definitions for the doc-forge CLI.
|
|
|
|
Provides the CLI structure using Click, including build, serve, and tree commands.
|
|
"""
|
|
|
|
from pathlib import Path
|
|
|
|
import click
|
|
|
|
from docforge.cli import mcp_utils, mkdocs_utils
|
|
from docforge.loaders import GriffeLoader
|
|
|
|
|
|
@click.group()
|
|
def cli() -> None:
|
|
"""
|
|
Root command group for the doc-forge CLI.
|
|
|
|
Provides commands for building, serving, and inspecting
|
|
documentation generated from Python source code.
|
|
"""
|
|
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")
|
|
@click.option("--site-name", help="MkDocs site name")
|
|
@click.option(
|
|
"--docs-dir",
|
|
type=click.Path(path_type=Path),
|
|
default=Path("docs/lib"),
|
|
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",
|
|
)
|
|
@click.option(
|
|
"--out-dir",
|
|
type=click.Path(path_type=Path),
|
|
default=Path("docs/mcp"),
|
|
help="MCP output directory",
|
|
)
|
|
def build(
|
|
mcp: bool,
|
|
mkdocs: bool,
|
|
module_is_source: bool,
|
|
module: str | None,
|
|
project_name: str | None,
|
|
site_name: str | None,
|
|
docs_dir: Path,
|
|
nav_file: Path,
|
|
template: Path | None,
|
|
mkdocs_yml: Path,
|
|
out_dir: Path,
|
|
) -> None:
|
|
"""
|
|
Build documentation artifacts.
|
|
|
|
This command performs the full documentation build pipeline:
|
|
|
|
1. Introspects the Python project using Griffe
|
|
2. Generates renderer-specific documentation sources
|
|
3. Optionally builds the final documentation output
|
|
|
|
Depending on the selected options, the build can target:
|
|
|
|
- MkDocs static documentation sites
|
|
- MCP structured documentation resources
|
|
|
|
Args:
|
|
mcp (bool):
|
|
Enable MCP documentation generation.
|
|
|
|
mkdocs (bool):
|
|
Enable MkDocs documentation generation.
|
|
|
|
module_is_source (bool):
|
|
Treat the specified module directory as the project root.
|
|
|
|
module (Optional[str]):
|
|
Python module import path to document.
|
|
|
|
project_name (Optional[str]):
|
|
Optional override for the project name.
|
|
|
|
site_name (Optional[str]):
|
|
Display name for the MkDocs site.
|
|
|
|
docs_dir (Path):
|
|
Directory where Markdown documentation sources will be generated.
|
|
|
|
nav_file (Path):
|
|
Path to the navigation specification file.
|
|
|
|
template (Optional[Path]):
|
|
Optional custom MkDocs configuration template.
|
|
|
|
mkdocs_yml (Path):
|
|
Output path for the generated MkDocs configuration.
|
|
|
|
out_dir (Path):
|
|
Output directory for generated MCP resources.
|
|
|
|
Raises:
|
|
click.UsageError:
|
|
If required options are missing or conflicting.
|
|
"""
|
|
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,
|
|
readme_dir=mkdocs_yml.parent,
|
|
)
|
|
|
|
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("docs/mcp"),
|
|
help="MCP root directory",
|
|
)
|
|
def serve(
|
|
mcp: bool,
|
|
mkdocs: 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 documentation
|
|
- An MCP server exposing structured documentation resources
|
|
|
|
Args:
|
|
mcp (bool):
|
|
Serve documentation using the MCP server.
|
|
|
|
mkdocs (bool):
|
|
Serve the MkDocs development site.
|
|
|
|
module (Optional[str]):
|
|
Python module import path to serve via MCP.
|
|
|
|
mkdocs_yml (Path):
|
|
Path to the MkDocs configuration file.
|
|
|
|
out_dir (Path):
|
|
Root directory containing MCP documentation resources.
|
|
|
|
Raises:
|
|
click.UsageError:
|
|
If invalid or conflicting options are provided.
|
|
"""
|
|
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: 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.
|
|
|
|
Args:
|
|
module (str):
|
|
Python module import path to introspect.
|
|
|
|
project_name (Optional[str]):
|
|
Optional name to display as the project 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:
|
|
"""
|
|
Recursively print a documentation object and its members.
|
|
|
|
This helper function traverses the documentation object graph
|
|
and prints each object with indentation to represent hierarchy.
|
|
|
|
Args:
|
|
obj:
|
|
Documentation object to print.
|
|
|
|
indent (str):
|
|
Current indentation prefix used for nested members.
|
|
"""
|
|
click.echo(f"{indent}├── {obj.name}")
|
|
for member in obj.get_all_members():
|
|
_print_object(member, indent + "│ ")
|