aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

cli-cleanup (#1)

Browse Source 
Reviewed-on: #1
Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-01-21 13:23:32 +00:00
committed by aetos
parent 15c59ab274
commit 94c1818103
38 changed files with 2206 additions and 1524 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docforge/cli/__init__.py
View File

@@ -6,11 +6,9 @@ with doc-forge.
## Available Commands
- **build**: Build documentation (MkDocs site or MCP resources).
- **serve**: Serve documentation (MkDocs or MCP).
- **tree**: Visualize the introspected project structure.
- **generate**: Create Markdown source files from Python code.
- **mkdocs**: Generate the primary `mkdocs.yml` configuration.
- **build**: Build the final documentation site.
- **serve**: Launch a local development server with live-reloading.
"""
from .main import main

135
docforge/cli/commands.py Normal file
View File

@@ -0,0 +1,135 @@
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", 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: 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).
"""
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, project_name, docs_dir)
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("--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,
mkdocs_yml: Path,
out_dir: Path,
) -> None:
"""
Serve documentation.
"""
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 mkdocs:
mkdocs_utils.serve(mkdocs_yml)
elif mcp:
mcp_utils.serve(out_dir)
@cli.command()
@click.option(
"--modules",
multiple=True,
required=True,
help="Python module import paths to introspect",
)
@click.option(
"--project-name",
help="Project name (defaults to first module)",
)
def tree(
modules: Sequence[str],
project_name: Optional[str],
) -> None:
"""
Visualize the project structure.
"""
loader = GriffeLoader()
project = loader.load_project(list(modules), 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.
"""
click.echo(f"{indent}├── {obj.name}")
for member in obj.get_all_members():
_print_object(member, indent + "│ ")

32
docforge/cli/commands.pyi Normal file
View File

@@ -0,0 +1,32 @@
from click.core import Group
from pathlib import Path
from typing import Sequence, Optional, Any
cli: Group
def build(
mcp: bool,
mkdocs: 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: ...
def serve(
mcp: bool,
mkdocs: bool,
mkdocs_yml: Path,
out_dir: Path,
) -> None: ...
def tree(
modules: Sequence[str],
project_name: Optional[str],
) -> None: ...
def _print_object(obj: Any, indent: str) -> None: ...

266
docforge/cli/main.py
View File

@@ -1,268 +1,7 @@
"""
Main entry point for the doc-forge CLI. This module defines the core command
group and the 'tree', 'generate', 'build', and 'serve' commands.
Main entry point for the doc-forge CLI.
"""
from pathlib import Path
from typing import Sequence, Optional
import click
from docforge.loaders import GriffeLoader, discover_module_paths
from docforge.renderers import MkDocsRenderer, MCPRenderer
from docforge.cli.mkdocs import mkdocs_cmd
@click.group()
def cli() -> None:
"""
doc-forge CLI: A tool for introspecting Python projects and generating
documentation.
"""
pass
cli.add_command(mkdocs_cmd)
# ---------------------------------------------------------------------
# tree
# ---------------------------------------------------------------------
@cli.command()
@click.option(
"--modules",
multiple=True,
required=True,
help="Python module import paths to introspect",
)
@click.option(
"--project-name",
help="Project name (defaults to first module)",
)
def tree(
modules: Sequence[str],
project_name: Optional[str],
) -> None:
"""
Visualize the project structure including modules and their members.
Args:
modules: List of module paths to introspect.
project_name: Optional project name override.
"""
loader = GriffeLoader()
project = loader.load_project(list(modules), 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 to print.
indent: The current line indentation string.
"""
click.echo(f"{indent}├── {obj.name}")
for member in obj.get_all_members():
_print_object(member, indent + "│ ")
# ---------------------------------------------------------------------
# generate
# ---------------------------------------------------------------------
@cli.command()
@click.option(
"--module",
required=True,
help="Python module import paths to document",
)
@click.option(
"--project-name",
help="Project name (defaults to first module)",
)
@click.option(
"--docs-dir",
type=click.Path(path_type=Path),
default=Path("docs"),
)
def generate(
module: str,
project_name: Optional[str],
docs_dir: Path,
) -> None:
"""
Generate Markdown source files for the specified module.
Args:
module: The primary module path to document.
project_name: Optional project name override.
docs_dir: Directory where documentation sources will be written.
"""
loader = GriffeLoader()
discovered_paths = discover_module_paths(
module,
)
project = loader.load_project(
discovered_paths,
project_name
)
renderer = MkDocsRenderer()
renderer.generate_sources(project, docs_dir)
click.echo(f"Documentation sources generated in {docs_dir}")
# ---------------------------------------------------------------------
# mcp-build
# ---------------------------------------------------------------------
@cli.command(name="generate-mcp")
@click.option(
"--module",
required=True,
help="Python module import path to document",
)
@click.option(
"--project-name",
help="Project name (defaults to first module)",
)
@click.option(
"--out-dir",
type=click.Path(path_type=Path),
default=Path("mcp_docs"),
)
def generate_mcp(
module: str,
project_name: str | None,
out_dir: Path,
) -> None:
"""
Generate MCP-compatible documentation resources for the specified module.
Args:
module: The primary module path to document.
project_name: Optional project name override.
out_dir: Directory where MCP resources will be written.
"""
loader = GriffeLoader()
discovered_paths = discover_module_paths(module)
project = loader.load_project(
discovered_paths,
project_name,
)
renderer = MCPRenderer()
renderer.generate_sources(project, out_dir)
click.echo(f"MCP documentation resources generated in {out_dir}")
# ---------------------------------------------------------------------
# build
# ---------------------------------------------------------------------
@cli.command()
@click.option(
"--mkdocs-yml",
type=click.Path(path_type=Path),
default=Path("mkdocs.yml"),
)
def build(mkdocs_yml: Path) -> None:
"""
Build the documentation site using MkDocs.
Args:
mkdocs_yml: Path to the mkdocs.yml configuration file.
"""
if not mkdocs_yml.exists():
raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
from mkdocs.config import load_config
from mkdocs.commands.build import build as mkdocs_build
mkdocs_build(load_config(str(mkdocs_yml)))
click.echo("MkDocs build completed")
# ---------------------------------------------------------------------
# serve-mcp
# ---------------------------------------------------------------------
@cli.command(name="serve-mcp")
def serve_mcp() -> None:
"""
Serve MCP documentation from the local mcp_docs directory.
"""
from docforge.servers import MCPServer
mcp_root = Path.cwd() / "mcp_docs"
if not mcp_root.exists():
raise click.ClickException("mcp_docs directory not found")
required = [
mcp_root / "index.json",
mcp_root / "nav.json",
mcp_root / "modules",
]
for path in required:
if not path.exists():
raise click.ClickException(f"Invalid MCP bundle, missing: {path.name}")
server = MCPServer(
mcp_root=mcp_root,
name="doc-forge-mcp",
)
server.run()
# ---------------------------------------------------------------------
# serve
# ---------------------------------------------------------------------
@cli.command()
@click.option(
"--mkdocs-yml",
type=click.Path(path_type=Path),
default=Path("mkdocs.yml"),
)
def serve(mkdocs_yml: Path) -> None:
"""
Serve the documentation site with live-reload using MkDocs.
Args:
mkdocs_yml: Path to the mkdocs.yml configuration file.
"""
if not mkdocs_yml.exists():
raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
from mkdocs.commands.serve import serve as mkdocs_serve
host = "127.0.0.1"
port = 8000
url = f"http://{host}:{port}/"
click.echo(f"Serving documentation at {url}")
mkdocs_serve(config_file=str(mkdocs_yml))
# ---------------------------------------------------------------------
# entry point
# ---------------------------------------------------------------------
from docforge.cli.commands import cli
def main() -> None:
"""
@@ -270,6 +9,5 @@ def main() -> None:
"""
cli()
if __name__ == "__main__":
main()

110
docforge/cli/main.pyi
View File

@@ -1,109 +1 @@
from typing import Sequence
from pathlib import Path
import click
@click.group()
def cli() -> None:
"""doc-forge command-line interface."""
@cli.command()
@click.option(
"--modules",
multiple=True,
help="Python module import paths to introspect",
)
@click.option(
"--project-name",
help="Project name (defaults to first module)",
)
def tree(
modules: Sequence[str],
project_name: str | None,
) -> None:
"""Show introspection tree."""
@cli.command()
@click.option(
"--module",
help="Python module import paths to document",
)
@click.option(
"--project-name",
help="Project name (defaults to first module)",
)
@click.option(
"--docs-dir",
type=click.Path(path_type=Path),
default=Path("docs"),
)
def generate(
module: str,
project_name: str | None,
docs_dir: Path,
) -> None:
"""Generate documentation source files using MkDocs renderer."""
@cli.command(name="generate-mcp")
@click.option(
"--module",
required=True,
help="Python module import path to document",
)
@click.option(
"--project-name",
help="Project name (defaults to first module)",
)
@click.option(
"--out-dir",
type=click.Path(path_type=Path),
default=Path("mcp_docs"),
)
def generate_mcp(
module: str,
project_name: str | None,
out_dir: Path,
) -> None:
"""
Generate MCP-compatible documentation resources for the specified module.
Args:
module: The primary module path to document.
project_name: Optional project name override.
out_dir: Directory where MCP resources will be written.
"""
@cli.command()
@click.option(
"--mkdocs-yml",
type=click.Path(path_type=Path),
default=Path("mkdocs.yml"),
)
def build(
mkdocs_yml: Path,
) -> None:
"""Build documentation using MkDocs."""
@cli.command()
@click.option(
"--mkdocs-yml",
type=click.Path(path_type=Path),
default=Path("mkdocs.yml"),
)
def serve(
mkdocs_yml: Path,
) -> None:
"""Serve documentation using MkDocs."""
@cli.command(name="serve-mcp")
def serve_mcp() -> None:
"""Serve MCP documentation."""
def main() -> None:
"""CLI entry point."""
def main() -> None: ...

39
docforge/cli/mcp_utils.py Normal file
View File

@@ -0,0 +1,39 @@
from pathlib import Path
import click
from docforge.loaders import GriffeLoader, discover_module_paths
from docforge.renderers import MCPRenderer
from docforge.servers import MCPServer
def generate_resources(module: str, project_name: str | None, out_dir: Path) -> None:
"""
Generate MCP-compatible documentation resources.
"""
loader = GriffeLoader()
discovered_paths = discover_module_paths(module)
project = loader.load_project(discovered_paths, project_name)
renderer = MCPRenderer()
renderer.generate_sources(project, out_dir)
def serve(mcp_root: Path) -> None:
"""
Serve MCP documentation.
"""
if not mcp_root.exists():
raise click.ClickException(f"mcp_docs directory not found: {mcp_root}")
required = [
mcp_root / "index.json",
mcp_root / "nav.json",
mcp_root / "modules",
]
for path in required:
if not path.exists():
raise click.ClickException(f"Invalid MCP bundle, missing: {path.name}")
server = MCPServer(
mcp_root=mcp_root,
name="doc-forge-mcp",
)
server.run()

4
docforge/cli/mcp_utils.pyi Normal file
View File

@@ -0,0 +1,4 @@
from pathlib import Path
def generate_resources(module: str, project_name: str | None, out_dir: Path) -> None: ...
def serve(mcp_root: Path) -> None: ...

116
docforge/cli/mkdocs.py
View File

@@ -1,116 +0,0 @@
"""
This module contains the 'mkdocs' CLI command, which orchestrates the generation
of the main mkdocs.yml configuration file.
"""
from pathlib import Path
from importlib import resources
import click
import yaml
from docforge.nav import load_nav_spec
from docforge.nav import resolve_nav
from docforge.nav import MkDocsNavEmitter
def _load_template(template: Path | None) -> dict:
"""
Load a YAML template for mkdocs.yml. If no template is provided,
loads the built-in sample template.
Args:
template: Path to the template file, or None.
Returns:
The loaded template data as a dictionary.
"""
if template is not None:
if not template.exists():
raise click.FileError(str(template), hint="Template not found")
return yaml.safe_load(template.read_text(encoding="utf-8"))
# Load built-in default
text = (
resources.files("docforge.templates")
.joinpath("mkdocs.sample.yml")
.read_text(encoding="utf-8")
)
return yaml.safe_load(text)
@click.command("mkdocs")
@click.option(
"--site-name",
required=True,
help="MkDocs site_name (required)",
)
@click.option(
"--docs-dir",
type=click.Path(path_type=Path),
default=Path("docs"),
)
@click.option(
"--nav",
"nav_file",
type=click.Path(path_type=Path),
default=Path("docforge.nav.yml"),
)
@click.option(
"--template",
type=click.Path(path_type=Path),
default=None,
help="Override the built-in mkdocs template",
)
@click.option(
"--out",
type=click.Path(path_type=Path),
default=Path("mkdocs.yml"),
)
def mkdocs_cmd(
docs_dir: Path,
nav_file: Path,
template: Path | None,
out: Path,
site_name: str,
) -> None:
"""
Generate an mkdocs.yml configuration file by combining a template with
the navigation structure resolved from a docforge.nav.yml file.
Args:
docs_dir: Path to the directory containing documentation Markdown files.
nav_file: Path to the docforge.nav.yml specification.
template: Optional path to an mkdocs.yml template.
out: Path where the final mkdocs.yml will be written.
site_name: The name of the documentation site.
"""
if not nav_file.exists():
raise click.FileError(str(nav_file), hint="Nav spec not found")
# Load nav spec
spec = load_nav_spec(nav_file)
# Resolve nav
resolved = resolve_nav(spec, docs_dir)
# Emit mkdocs nav
nav_block = MkDocsNavEmitter().emit(resolved)
# Load template (user or built-in)
data = _load_template(template)
# Inject site_name
data["site_name"] = site_name
# Inject nav
data["nav"] = nav_block
# Write output
out.write_text(
yaml.safe_dump(data, sort_keys=False),
encoding="utf-8",
)
click.echo(f"mkdocs.yml written to {out}")

45
docforge/cli/mkdocs.pyi
View File

@@ -1,45 +0,0 @@
from pathlib import Path
from typing import Any, Dict, Optional
import click
def _load_template(template: Optional[Path]) -> Dict[str, Any]:
...
@click.command("mkdocs")
@click.option(
"--site-name",
required=True,
help="MkDocs site_name (required)",
)
@click.option(
"--docs-dir",
type=click.Path(path_type=Path),
default=Path("docs"),
)
@click.option(
"--nav",
"nav_file",
type=click.Path(path_type=Path),
default=Path("docforge.nav.yml"),
)
@click.option(
"--template",
type=click.Path(path_type=Path),
default=None,
)
@click.option(
"--out",
type=click.Path(path_type=Path),
default=Path("mkdocs.yml"),
)
def mkdocs_cmd(
docs_dir: Path,
nav_file: Path,
template: Optional[Path],
out: Path,
site_name: str,
) -> None:
...

69
docforge/cli/mkdocs_utils.py Normal file
View File

@@ -0,0 +1,69 @@
from pathlib import Path
from importlib import resources
import click
import yaml
from docforge.loaders import GriffeLoader, discover_module_paths
from docforge.renderers import MkDocsRenderer
from docforge.nav import load_nav_spec, resolve_nav, MkDocsNavEmitter
def generate_sources(module: str, project_name: str | None, docs_dir: Path) -> None:
"""
Generate Markdown source files for the specified module.
"""
loader = GriffeLoader()
discovered_paths = discover_module_paths(module)
project = loader.load_project(discovered_paths, project_name)
renderer = MkDocsRenderer()
renderer.generate_sources(project, docs_dir)
def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None:
"""
Generate an mkdocs.yml configuration file.
"""
if not nav_file.exists():
raise click.FileError(str(nav_file), hint="Nav spec not found")
spec = load_nav_spec(nav_file)
resolved = resolve_nav(spec, docs_dir)
nav_block = MkDocsNavEmitter().emit(resolved)
# Load template
if template is not None:
if not template.exists():
raise click.FileError(str(template), hint="Template not found")
data = yaml.safe_load(template.read_text(encoding="utf-8"))
else:
text = (
resources.files("docforge.templates")
.joinpath("mkdocs.sample.yml")
.read_text(encoding="utf-8")
)
data = yaml.safe_load(text)
data["site_name"] = site_name
data["nav"] = nav_block
out.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
def build(mkdocs_yml: Path) -> None:
"""
Build the documentation site using MkDocs.
"""
if not mkdocs_yml.exists():
raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
from mkdocs.config import load_config
from mkdocs.commands.build import build as mkdocs_build
mkdocs_build(load_config(str(mkdocs_yml)))
def serve(mkdocs_yml: Path) -> None:
"""
Serve the documentation site with live-reload using MkDocs.
"""
if not mkdocs_yml.exists():
raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
from mkdocs.commands.serve import serve as mkdocs_serve
mkdocs_serve(config_file=str(mkdocs_yml))

6
docforge/cli/mkdocs_utils.pyi Normal file
View File

@@ -0,0 +1,6 @@
from pathlib import Path
def generate_sources(module: str, project_name: str | None, docs_dir: Path) -> None: ...
def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None: ...
def build(mkdocs_yml: Path) -> None: ...
def serve(mkdocs_yml: Path) -> None: ...