refactor: restructure CLI and improve documentation/typing
- Consolidated CLI commands into [build](cci:1://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/mkdocs/logic.py:48:0-58:46) and [serve](cci:1://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/commands.py:70:0-92:32) using `--mkdocs` and `--mcp` flags. - Separated CLI orchestration logic into [docforge/cli/mkdocs/logic.py](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/mkdocs/logic.py:0:0-0:0) and [docforge/cli/mcp/logic.py](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/mcp/logic.py:0:0-0:0). - Moved command definitions to [docforge/cli/commands.py](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/commands.py:0:0-0:0), making [main.py](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/main.py:0:0-0:0) a thin entry point. - Aligned [.pyi](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/main.pyi:0:0-0:0) type stubs with [.py](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/tests/conftest.py:0:0-0:0) implementations across the package. - Added missing docstrings to internal helper functions and core classes. - Restructured tests into `tests/mkdocs/` and `tests/mcp/`. - Updated navigation specification to reflect the new project structure.
This commit is contained in:
129
docforge/cli/commands.py
Normal file
129
docforge/cli/commands.py
Normal file
@@ -0,0 +1,129 @@
|
||||
import click
|
||||
from pathlib import Path
|
||||
from typing import Sequence, Optional
|
||||
from docforge.loaders import GriffeLoader
|
||||
from docforge.cli.mkdocs import logic as mkdocs_logic
|
||||
from docforge.cli.mcp import logic as mcp_logic
|
||||
|
||||
@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_logic.generate_sources(module, project_name, docs_dir)
|
||||
|
||||
click.echo(f"Generating MkDocs config {mkdocs_yml}...")
|
||||
mkdocs_logic.generate_config(docs_dir, nav_file, template, mkdocs_yml, site_name)
|
||||
|
||||
click.echo("Running MkDocs build...")
|
||||
mkdocs_logic.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_logic.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_logic.serve(mkdocs_yml)
|
||||
elif mcp:
|
||||
mcp_logic.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 + "│ ")
|
||||
@@ -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()
|
||||
|
||||
@@ -1,109 +0,0 @@
|
||||
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."""
|
||||
0
docforge/cli/mcp/__init__.py
Normal file
0
docforge/cli/mcp/__init__.py
Normal file
39
docforge/cli/mcp/logic.py
Normal file
39
docforge/cli/mcp/logic.py
Normal 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()
|
||||
@@ -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}")
|
||||
@@ -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:
|
||||
...
|
||||
0
docforge/cli/mkdocs/__init__.py
Normal file
0
docforge/cli/mkdocs/__init__.py
Normal file
69
docforge/cli/mkdocs/logic.py
Normal file
69
docforge/cli/mkdocs/logic.py
Normal 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))
|
||||
Reference in New Issue
Block a user