40dc5354a5
Add references/workflows/engineering-drawing.md (preliminary staged workflow: preconditions -> declare views -> declare datums/dims -> solve and audit -> render and visual review) and references/domains/ engineering-drawing.md (capability boundary, R1-R7 solver contract, API groups, known engine limits, failure modes). Route the new goal in SKILL.md. Backfill docstrings for the dxf_engine public surface (declaration dataclasses, SheetPlan, render_plan) so auto_docs_gen can produce their API pages under references/docs/api/ with an Engineering Drawings index section, following the inspect/brep sub-namespace pattern.
1359 lines
48 KiB
Python
1359 lines
48 KiB
Python
#!/usr/bin/env python3
|
|
"""Generate markdown API docs from source files.
|
|
|
|
The generator extracts top-level public functions from source files,
|
|
parses their docstrings, and writes API markdown pages plus an index page.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import ast
|
|
import textwrap
|
|
from dataclasses import dataclass
|
|
from pathlib import Path
|
|
from typing import Dict, Iterable, List, Sequence
|
|
|
|
DEFAULT_SOURCE_FILENAMES: tuple[str, ...] = (
|
|
"operators/geometry.py",
|
|
"operators/transform.py",
|
|
"operators/boolean.py",
|
|
"operators/product.py",
|
|
"operators/sketch.py",
|
|
"operators/selection.py",
|
|
"operators/features.py",
|
|
"ql.py",
|
|
"recording/serializer.py",
|
|
"math.py",
|
|
"product/placement.py",
|
|
"product/material.py",
|
|
"product/connector.py",
|
|
"product/constraint.py",
|
|
"product/part.py",
|
|
"product/assembly.py",
|
|
"product/solver.py",
|
|
"params/expr.py",
|
|
"params/tolerance.py",
|
|
"params/units.py",
|
|
"recording/graph.py",
|
|
"sketch.py",
|
|
"errors.py",
|
|
"product/capture.py",
|
|
"product/packages.py",
|
|
"topology/model.py",
|
|
"dxf_engine/model.py",
|
|
"dxf_engine/planner.py",
|
|
"dxf_engine/render.py",
|
|
"build/assembly_builder.py",
|
|
"build/dependencies.py",
|
|
"build/incremental_solver.py",
|
|
"build/part_builder.py",
|
|
"build/results.py",
|
|
"cache/policy.py",
|
|
"cache/records.py",
|
|
"cache/store.py",
|
|
"inverse_engineer/brep/evaluation.py",
|
|
"inspect/brep/compare.py",
|
|
"inspect/brep/diagnostics.py",
|
|
"inspect/brep/fitting.py",
|
|
"inspect/brep/inspect.py",
|
|
"inspect/brep/io.py",
|
|
"inspect/brep/manufacturing.py",
|
|
"inspect/brep/model.py",
|
|
"inspect/brep/parity.py",
|
|
"inspect/brep/persistence.py",
|
|
"inspect/brep/queries.py",
|
|
"inspect/brep/render.py",
|
|
"inspect/brep/section_tracking.py",
|
|
"inspect/brep/slices.py",
|
|
"exporter/step.py",
|
|
"exporter/obj.py",
|
|
"exporter/stl.py",
|
|
"exporter/mjcf.py",
|
|
"inspect/brep/snapshots.py",
|
|
"inspect/brep/topology_inspection.py",
|
|
)
|
|
|
|
DEFAULT_STDLIB_SOURCE_FILENAMES: tuple[str, ...] = (
|
|
"std/bearing.py",
|
|
"std/gear.py",
|
|
)
|
|
|
|
FULL_PUBLIC_FUNCTION_MODULES = frozenset(
|
|
{
|
|
"operators/geometry.py",
|
|
"operators/transform.py",
|
|
"operators/boolean.py",
|
|
"operators/product.py",
|
|
"operators/sketch.py",
|
|
"operators/selection.py",
|
|
"operators/features.py",
|
|
"ql.py",
|
|
"math.py",
|
|
"product/placement.py",
|
|
}
|
|
)
|
|
|
|
EXPORTED_FUNCTION_MODULES = frozenset(
|
|
{
|
|
"recording/serializer.py",
|
|
"recording/graph.py",
|
|
"params/expr.py",
|
|
"params/tolerance.py",
|
|
"params/units.py",
|
|
"errors.py",
|
|
"product/capture.py",
|
|
"product/packages.py",
|
|
"product/solver.py",
|
|
"product/connector.py",
|
|
"product/placement.py",
|
|
"build/assembly_builder.py",
|
|
"build/dependencies.py",
|
|
"build/part_builder.py",
|
|
"cache/policy.py",
|
|
"inverse_engineer/brep/evaluation.py",
|
|
"inspect/brep/compare.py",
|
|
"inspect/brep/diagnostics.py",
|
|
"inspect/brep/fitting.py",
|
|
"inspect/brep/inspect.py",
|
|
"inspect/brep/io.py",
|
|
"inspect/brep/manufacturing.py",
|
|
"inspect/brep/model.py",
|
|
"inspect/brep/parity.py",
|
|
"inspect/brep/persistence.py",
|
|
"inspect/brep/queries.py",
|
|
"inspect/brep/render.py",
|
|
"inspect/brep/section_tracking.py",
|
|
"inspect/brep/slices.py",
|
|
"exporter/step.py",
|
|
"exporter/obj.py",
|
|
"exporter/stl.py",
|
|
"exporter/mjcf.py",
|
|
"inspect/brep/snapshots.py",
|
|
"inspect/brep/topology_inspection.py",
|
|
}
|
|
)
|
|
|
|
EXPORTED_CALLABLE_MODULES = frozenset(
|
|
{
|
|
"params/expr.py",
|
|
"params/tolerance.py",
|
|
"params/units.py",
|
|
"recording/graph.py",
|
|
"sketch.py",
|
|
"errors.py",
|
|
"topology/model.py",
|
|
"math.py",
|
|
"product/placement.py",
|
|
"product/material.py",
|
|
"product/connector.py",
|
|
"product/constraint.py",
|
|
"product/part.py",
|
|
"product/assembly.py",
|
|
}
|
|
)
|
|
|
|
MISSING = object()
|
|
|
|
|
|
def _repo_root_from(module_file: Path | str | None = None) -> Path:
|
|
target = Path(module_file) if module_file is not None else Path(__file__)
|
|
repo_root = target.resolve().parents[1]
|
|
if not (repo_root / "pyproject.toml").is_file():
|
|
raise FileNotFoundError(f"project root not found above {target}")
|
|
return repo_root
|
|
|
|
|
|
def _package_root_from(module_file: Path | str | None = None) -> Path:
|
|
return _repo_root_from(module_file) / "src" / "simplecadapi"
|
|
|
|
|
|
def _default_source_files(package_root: Path) -> List[Path]:
|
|
source_files = [package_root / name for name in DEFAULT_SOURCE_FILENAMES]
|
|
translator_root = package_root / "translator"
|
|
for backend_dir in sorted(translator_root.glob("*_translator")):
|
|
source_files.extend([backend_dir / "api.py", backend_dir / "translator.py"])
|
|
types_file = backend_dir / "types.py"
|
|
if types_file.is_file():
|
|
source_files.append(types_file)
|
|
return source_files
|
|
|
|
|
|
def _translator_backend_name(module_name: str) -> str | None:
|
|
parts = module_name.split("/")
|
|
if (
|
|
len(parts) == 3
|
|
and parts[0] == "translator"
|
|
and parts[1].endswith("_translator")
|
|
and parts[2] in {"api.py", "translator.py", "types.py"}
|
|
):
|
|
return parts[1]
|
|
return None
|
|
|
|
|
|
def _default_stdlib_source_files(package_root: Path) -> List[Path]:
|
|
return [package_root / name for name in DEFAULT_STDLIB_SOURCE_FILENAMES]
|
|
|
|
|
|
def _default_output_dirs(module_file: Path | str | None = None) -> List[Path]:
|
|
return [_repo_root_from(module_file) / "docs/skill/references/docs/api"]
|
|
|
|
|
|
def _default_stdlib_output_dirs(module_file: Path | str | None = None) -> List[Path]:
|
|
return [_repo_root_from(module_file) / "docs/skill/references/docs/stdlib"]
|
|
|
|
|
|
@dataclass
|
|
class ApiInfo:
|
|
"""Container for extracted API metadata."""
|
|
|
|
name: str
|
|
kind: str
|
|
signature: str
|
|
source_file: str
|
|
parsed_doc: Dict[str, object]
|
|
import_surface: str
|
|
doc_filename: str = ""
|
|
|
|
|
|
class APIDocumentGenerator:
|
|
"""Generate markdown docs for API functions."""
|
|
|
|
def __init__(
|
|
self,
|
|
source_files: Sequence[Path],
|
|
output_dirs: Sequence[Path],
|
|
clean_stale: bool = True,
|
|
quiet: bool = False,
|
|
):
|
|
self.source_files = list(source_files)
|
|
self.output_dirs = list(output_dirs)
|
|
self.clean_stale = clean_stale
|
|
self.quiet = quiet
|
|
self.apis: List[ApiInfo] = []
|
|
self.exported_names = self._load_top_level_exports()
|
|
|
|
def log(self, message: str) -> None:
|
|
if not self.quiet:
|
|
print(message)
|
|
|
|
def extract_apis(self) -> List[ApiInfo]:
|
|
"""Extract supported public callables with docstrings."""
|
|
self.log("正在分析源文件...")
|
|
|
|
extracted: List[ApiInfo] = []
|
|
exported_names = self.exported_names
|
|
for file_path in self.source_files:
|
|
if not file_path.exists():
|
|
self.log(f"警告: 找不到文件 {file_path},跳过。")
|
|
continue
|
|
|
|
self.log(f" 正在处理 {file_path}...")
|
|
source = file_path.read_text(encoding="utf-8")
|
|
tree = ast.parse(source, filename=str(file_path))
|
|
module_name = self._module_name_for(file_path)
|
|
|
|
file_count = 0
|
|
for node in tree.body:
|
|
api_info = self._extract_api_info(node, module_name, exported_names)
|
|
if api_info is None:
|
|
continue
|
|
|
|
extracted.append(api_info)
|
|
file_count += 1
|
|
|
|
self.log(f" 从 {file_path.name} 提取到 {file_count} 个API")
|
|
|
|
self.apis = self._assign_doc_filenames(extracted)
|
|
self.log(f"成功总共提取到 {len(self.apis)} 个API")
|
|
return self.apis
|
|
|
|
def _module_name_for(self, file_path: Path) -> str:
|
|
# Climb to the topmost package directory containing this file (the
|
|
# highest ancestor still holding an __init__.py) and express the
|
|
# module relative to it; fall back to the basename for loose files.
|
|
current = file_path.parent
|
|
topmost: Path | None = None
|
|
while (current / "__init__.py").exists():
|
|
topmost = current
|
|
parent = current.parent
|
|
if parent == current:
|
|
break
|
|
current = parent
|
|
if topmost is not None:
|
|
try:
|
|
return file_path.resolve().relative_to(topmost.resolve()).as_posix()
|
|
except ValueError:
|
|
pass
|
|
return file_path.name
|
|
|
|
@staticmethod
|
|
def _assign_doc_filenames(apis: List[ApiInfo]) -> List[ApiInfo]:
|
|
counts: Dict[str, int] = {}
|
|
assigned: List[ApiInfo] = []
|
|
|
|
for api in apis:
|
|
base = api.name
|
|
lowered = base.lower()
|
|
counts[lowered] = counts.get(lowered, 0) + 1
|
|
if counts[lowered] == 1:
|
|
filename = f"{base}.md"
|
|
else:
|
|
filename = f"{base}_{api.kind}.md"
|
|
assigned.append(
|
|
ApiInfo(
|
|
name=api.name,
|
|
kind=api.kind,
|
|
signature=api.signature,
|
|
source_file=api.source_file,
|
|
parsed_doc=api.parsed_doc,
|
|
import_surface=api.import_surface,
|
|
doc_filename=filename,
|
|
)
|
|
)
|
|
|
|
return assigned
|
|
|
|
def _extract_api_info(
|
|
self,
|
|
node: ast.stmt,
|
|
module_name: str,
|
|
exported_names: set[str],
|
|
) -> ApiInfo | None:
|
|
if isinstance(node, ast.FunctionDef):
|
|
if not self._should_include_function(
|
|
node.name, module_name, exported_names
|
|
):
|
|
return None
|
|
|
|
docstring = ast.get_docstring(node)
|
|
if not docstring:
|
|
return None
|
|
|
|
return ApiInfo(
|
|
name=node.name,
|
|
kind="function",
|
|
signature=self._get_function_signature(node),
|
|
source_file=module_name,
|
|
parsed_doc=self._parse_docstring(docstring),
|
|
import_surface=self._import_surface_for(node.name, module_name),
|
|
)
|
|
|
|
if isinstance(node, ast.ClassDef):
|
|
if not self._should_include_class(node.name, module_name, exported_names):
|
|
return None
|
|
|
|
docstring = ast.get_docstring(node)
|
|
if not docstring:
|
|
return None
|
|
|
|
return ApiInfo(
|
|
name=node.name,
|
|
kind="class",
|
|
signature=self._get_class_signature(node),
|
|
source_file=module_name,
|
|
parsed_doc=self._parse_docstring(docstring),
|
|
import_surface=self._import_surface_for(node.name, module_name),
|
|
)
|
|
|
|
return None
|
|
|
|
@staticmethod
|
|
def _should_include_function(
|
|
name: str,
|
|
module_name: str,
|
|
exported_names: set[str],
|
|
) -> bool:
|
|
if name.startswith("_"):
|
|
return False
|
|
if module_name.startswith("exporter/"):
|
|
return True
|
|
if name.startswith("_"):
|
|
return False
|
|
if module_name in FULL_PUBLIC_FUNCTION_MODULES:
|
|
return True
|
|
if _translator_backend_name(module_name) is not None:
|
|
return True
|
|
if module_name.startswith("inspect/brep/"):
|
|
return name.endswith(
|
|
(
|
|
"_rbrepcomparison",
|
|
"_rbrepinspection",
|
|
"_rbrepmodel",
|
|
"_rdescriptor",
|
|
"_rdescriptorlist",
|
|
"_rentityinspectionparity",
|
|
"_rinspectionsummarycomparison",
|
|
"_rnone",
|
|
"_rpath",
|
|
"_rshape",
|
|
"_rslicecomparison",
|
|
"_rslicespeclist",
|
|
"_rsummary",
|
|
"_rtuple",
|
|
)
|
|
)
|
|
if module_name == "inverse_engineer/brep/evaluation.py":
|
|
return name in {
|
|
"classify_benchmark_result",
|
|
"inspect_benchmark_step",
|
|
"run_comparison_bundle",
|
|
}
|
|
if module_name.startswith("dxf_engine/"):
|
|
return name in {"render_plan"}
|
|
if module_name in EXPORTED_FUNCTION_MODULES:
|
|
if not exported_names:
|
|
return True
|
|
return name in exported_names
|
|
return False
|
|
|
|
@staticmethod
|
|
def _should_include_class(
|
|
name: str,
|
|
module_name: str,
|
|
exported_names: set[str],
|
|
) -> bool:
|
|
if name.startswith("_"):
|
|
return False
|
|
if module_name.startswith("exporter/"):
|
|
return True
|
|
if _translator_backend_name(module_name) is not None:
|
|
return True
|
|
if module_name.startswith("inspect/brep/"):
|
|
return name in {
|
|
"BRepComparison",
|
|
"BRepEntityError",
|
|
"BRepInspection",
|
|
"BRepModel",
|
|
"EntityInspectionParity",
|
|
"InspectionSummaryComparison",
|
|
"SliceComparison",
|
|
"SlicePanelResult",
|
|
"SliceSpec",
|
|
}
|
|
if module_name == "inverse_engineer/brep/evaluation.py":
|
|
return name in {"EvaluationConfig", "SectionEvaluationConfig"}
|
|
if module_name.startswith("dxf_engine/"):
|
|
return name in {
|
|
"SheetDecl",
|
|
"ViewDecl",
|
|
"DimDecl",
|
|
"DatumDecl",
|
|
"CenterDecl",
|
|
"LeaderDecl",
|
|
"SheetPlan",
|
|
"Resolved",
|
|
}
|
|
if name in exported_names:
|
|
return True
|
|
if module_name not in EXPORTED_CALLABLE_MODULES:
|
|
return False
|
|
if not exported_names:
|
|
return True
|
|
return name in exported_names
|
|
|
|
def _load_top_level_exports(self) -> set[str]:
|
|
init_file = self._find_top_level_init_file()
|
|
if init_file is None or not init_file.exists():
|
|
return set()
|
|
|
|
tree = ast.parse(init_file.read_text(encoding="utf-8"), filename=str(init_file))
|
|
for node in tree.body:
|
|
if not isinstance(node, ast.Assign):
|
|
continue
|
|
if len(node.targets) != 1:
|
|
continue
|
|
target = node.targets[0]
|
|
if not isinstance(target, ast.Name) or target.id != "__all__":
|
|
continue
|
|
if not isinstance(node.value, (ast.List, ast.Tuple)):
|
|
continue
|
|
|
|
exported: set[str] = set()
|
|
for item in node.value.elts:
|
|
if isinstance(item, ast.Constant) and isinstance(item.value, str):
|
|
exported.add(item.value)
|
|
return exported
|
|
return set()
|
|
|
|
def _import_surface_for(self, name: str, module_name: str) -> str:
|
|
if module_name == "inverse_engineer/brep/evaluation.py":
|
|
return (
|
|
"reverse-engineering evaluator: `from simplecadapi.inverse_engineer.brep "
|
|
f"import {name}`"
|
|
)
|
|
|
|
if name in self.exported_names:
|
|
return f"top-level: `from simplecadapi import {name}`"
|
|
|
|
if module_name.startswith("exporter/"):
|
|
exporter_module = module_name.removeprefix("exporter/").removesuffix(".py")
|
|
return (
|
|
f"exporter namespace: `from simplecadapi import exporter` "
|
|
f"then `exporter.{exporter_module}.{name}(...)`"
|
|
)
|
|
|
|
translator_backend = _translator_backend_name(module_name)
|
|
if translator_backend is not None:
|
|
return (
|
|
"translator backend: "
|
|
f"`from simplecadapi.translator.{translator_backend} import {name}`"
|
|
)
|
|
|
|
if module_name.startswith("inspect/brep/"):
|
|
return (
|
|
"inspection namespace: `from simplecadapi.inspect import brep` "
|
|
f"then `brep.{name}(...)`; unavailable inside GraphSession"
|
|
)
|
|
|
|
if module_name.startswith("dxf_engine/"):
|
|
return (
|
|
"drawing namespace: "
|
|
f"`from simplecadapi.dxf_engine import {name}`"
|
|
)
|
|
|
|
module_stem = module_name.removesuffix(".py")
|
|
if module_stem in {"field", "ql"}:
|
|
return (
|
|
f"submodule: `from simplecadapi.{module_stem} import {name}` "
|
|
f"or `simplecadapi.{module_stem}.{name}`"
|
|
)
|
|
|
|
return f"submodule: `from simplecadapi.{module_stem} import {name}`"
|
|
|
|
def _find_top_level_init_file(self) -> Path | None:
|
|
# Climb from each source file to the topmost package directory (the
|
|
# highest ancestor still holding an __init__.py); source files now
|
|
# live in subpackages, so their immediate parent init is not the
|
|
# top-level one.
|
|
for source_file in self.source_files:
|
|
current = source_file.parent
|
|
topmost: Path | None = None
|
|
while (current / "__init__.py").exists():
|
|
topmost = current / "__init__.py"
|
|
parent = current.parent
|
|
if parent == current:
|
|
break
|
|
current = parent
|
|
if topmost is not None:
|
|
return topmost
|
|
return None
|
|
|
|
def generate_markdown_docs(self) -> None:
|
|
"""Generate markdown docs for all configured output directories."""
|
|
if not self.apis:
|
|
self.log("没有可生成的API文档。")
|
|
return
|
|
|
|
for output_dir in self.output_dirs:
|
|
self._generate_for_single_output_dir(output_dir)
|
|
|
|
def _generate_for_single_output_dir(self, output_dir: Path) -> None:
|
|
output_dir.mkdir(parents=True, exist_ok=True)
|
|
self.log(f"正在生成markdown文档到: {output_dir}")
|
|
|
|
generated_files = set()
|
|
created_or_updated = 0
|
|
|
|
for api in sorted(self.apis, key=lambda item: item.name):
|
|
filename = api.doc_filename or f"{api.name}.md"
|
|
file_path = output_dir / filename
|
|
md_content = self._build_single_api_markdown(api)
|
|
changed = self._write_if_changed(file_path, md_content)
|
|
if changed:
|
|
created_or_updated += 1
|
|
generated_files.add(filename)
|
|
|
|
readme_path = output_dir / "README.md"
|
|
readme_content = self._build_api_index_markdown()
|
|
if self._write_if_changed(readme_path, readme_content):
|
|
created_or_updated += 1
|
|
|
|
removed_count = 0
|
|
if self.clean_stale:
|
|
removed_count = self._remove_stale_docs(output_dir, generated_files)
|
|
|
|
self.log(
|
|
f"文档生成完成: {output_dir} "
|
|
f"(更新 {created_or_updated} 个文件, 删除 {removed_count} 个过期文档)"
|
|
)
|
|
|
|
def _build_single_api_markdown(self, api: ApiInfo) -> str:
|
|
parsed = api.parsed_doc
|
|
md_lines: List[str] = []
|
|
definition_title = (
|
|
"Class Definition" if api.kind == "class" else "API Definition"
|
|
)
|
|
|
|
md_lines.append(f"# {api.name}")
|
|
md_lines.append("")
|
|
|
|
md_lines.append(f"## {definition_title}")
|
|
md_lines.append("")
|
|
md_lines.append("```python")
|
|
md_lines.append(api.signature)
|
|
md_lines.append("```")
|
|
md_lines.append("")
|
|
md_lines.append(f"*Source: {api.source_file}*")
|
|
md_lines.append("")
|
|
|
|
md_lines.append("## Import Surface")
|
|
md_lines.append("")
|
|
md_lines.append(f"- {api.import_surface}")
|
|
md_lines.append("")
|
|
|
|
description = str(parsed.get("description", "")).strip()
|
|
usage = str(parsed.get("usage", "")).strip()
|
|
usage_parts = [part for part in [description, usage] if part]
|
|
if usage_parts:
|
|
merged_usage = "\n\n".join(dict.fromkeys(usage_parts))
|
|
md_lines.append("## Description")
|
|
md_lines.append("")
|
|
md_lines.extend(merged_usage.splitlines())
|
|
md_lines.append("")
|
|
|
|
args = parsed.get("args", [])
|
|
if isinstance(args, list) and args:
|
|
md_lines.append("## Parameters")
|
|
md_lines.append("")
|
|
for arg in args:
|
|
arg_name = str(arg.get("name", "")).strip()
|
|
arg_type = str(arg.get("type", "")).strip()
|
|
arg_desc = str(arg.get("description", "")).strip()
|
|
|
|
md_lines.append(f"### {arg_name}")
|
|
md_lines.append("")
|
|
if arg_type:
|
|
md_lines.append(f"- **Type**: `{arg_type}`")
|
|
md_lines.append(f"- **Description**: {arg_desc}")
|
|
md_lines.append("")
|
|
|
|
returns_text = str(parsed.get("returns", "")).strip()
|
|
if returns_text:
|
|
md_lines.append("## Returns")
|
|
md_lines.append("")
|
|
md_lines.extend(returns_text.splitlines())
|
|
md_lines.append("")
|
|
|
|
raises = parsed.get("raises", [])
|
|
if isinstance(raises, list) and raises:
|
|
md_lines.append("## Raises")
|
|
md_lines.append("")
|
|
for exc in raises:
|
|
exc_type = str(exc.get("type", "")).strip()
|
|
exc_desc = str(exc.get("description", "")).strip()
|
|
md_lines.append(f"- **{exc_type}**: {exc_desc}")
|
|
md_lines.append("")
|
|
|
|
examples = parsed.get("examples", [])
|
|
if isinstance(examples, list) and examples:
|
|
md_lines.append("## Examples")
|
|
md_lines.append("")
|
|
for index, block in enumerate(examples, start=1):
|
|
if len(examples) > 1:
|
|
md_lines.append(f"### Example {index}")
|
|
md_lines.append("```python")
|
|
md_lines.extend(block.splitlines())
|
|
md_lines.append("```")
|
|
md_lines.append("")
|
|
|
|
return "\n".join(md_lines).rstrip() + "\n"
|
|
|
|
def _build_api_index_markdown(self) -> str:
|
|
categories: Dict[str, List[ApiInfo]] = {
|
|
"Basic Creation": [],
|
|
"Transforms": [],
|
|
"3D Operations": [],
|
|
"Tagging and Selection": [],
|
|
"Boolean Operations": [],
|
|
"Export": [],
|
|
"Translator Backends": [],
|
|
"Math Helpers": [],
|
|
"Modeling Graph and Replay": [],
|
|
"Expressions and Parameters": [],
|
|
"Physical Units": [],
|
|
"Types and Errors": [],
|
|
"Advanced Features": [],
|
|
"STEP/BREP Inspection": [],
|
|
"Product Build and Cache": [],
|
|
"Reconstruction Evaluation": [],
|
|
"Engineering Drawings": [],
|
|
"Other": [],
|
|
}
|
|
|
|
for api in self.apis:
|
|
name = api.name
|
|
|
|
if api.source_file.startswith("inspect/brep/"):
|
|
categories["STEP/BREP Inspection"].append(api)
|
|
continue
|
|
if api.source_file.startswith(("build/", "cache/")):
|
|
categories["Product Build and Cache"].append(api)
|
|
continue
|
|
|
|
if api.source_file == "inverse_engineer/brep/evaluation.py":
|
|
categories["Reconstruction Evaluation"].append(api)
|
|
continue
|
|
|
|
if api.source_file.startswith("dxf_engine/"):
|
|
categories["Engineering Drawings"].append(api)
|
|
continue
|
|
|
|
if api.source_file in {"recording/serializer.py", "recording/graph.py"}:
|
|
categories["Modeling Graph and Replay"].append(api)
|
|
continue
|
|
|
|
if api.source_file.startswith("exporter/"):
|
|
categories["Export"].append(api)
|
|
continue
|
|
if _translator_backend_name(api.source_file) is not None:
|
|
categories["Translator Backends"].append(api)
|
|
continue
|
|
|
|
if api.source_file == "math.py":
|
|
categories["Math Helpers"].append(api)
|
|
continue
|
|
|
|
if api.source_file in {"params/expr.py", "params/tolerance.py"}:
|
|
categories["Expressions and Parameters"].append(api)
|
|
continue
|
|
|
|
if api.source_file == "params/units.py":
|
|
categories["Physical Units"].append(api)
|
|
continue
|
|
|
|
if api.source_file in {"sketch.py", "errors.py"}:
|
|
categories["Types and Errors"].append(api)
|
|
continue
|
|
|
|
if name.startswith("make_"):
|
|
categories["Basic Creation"].append(api)
|
|
elif name.startswith(("translate_", "rotate_", "mirror_")):
|
|
categories["Transforms"].append(api)
|
|
elif name.startswith(("extrude_", "revolve_", "loft_", "sweep_")):
|
|
categories["3D Operations"].append(api)
|
|
elif name.startswith(("apply_tag", "list_tags", "select_")):
|
|
categories["Tagging and Selection"].append(api)
|
|
elif name.startswith(("union_", "cut_", "intersect_")):
|
|
categories["Boolean Operations"].append(api)
|
|
elif name.startswith("export_"):
|
|
categories["Export"].append(api)
|
|
elif name.startswith(
|
|
("fillet_", "chamfer_", "shell_", "pattern_", "helical_")
|
|
):
|
|
categories["Advanced Features"].append(api)
|
|
else:
|
|
categories["Other"].append(api)
|
|
|
|
md_lines: List[str] = [
|
|
"# SimpleCAD API Index",
|
|
"",
|
|
"This index includes generated docs for the public SimpleCAD API surface, including geometry operations, graph/model JSON workflows, durable product builds, persistent cache controls, inspection tools, expressions, QL, and export helpers.",
|
|
"",
|
|
"## Import Surfaces",
|
|
"",
|
|
"- Entries marked `top-level` are exported from `simplecadapi` and can be imported with `from simplecadapi import <name>`.",
|
|
"- Entries marked `submodule` are public through the listed submodule, such as `simplecadapi.ql`.",
|
|
"- Entries marked `inspection namespace` are available through `simplecadapi.inspect.brep` and cannot run inside `GraphSession`.",
|
|
"- Entries marked `translator backend` are public only through `simplecadapi.translator.<backend>`.",
|
|
"- Entries marked `reverse-engineering evaluator` are available through `simplecadapi.inverse_engineer.brep`; their acceptance inputs and reports belong to the trusted harness, not participant code.",
|
|
"",
|
|
]
|
|
|
|
for category, api_list in categories.items():
|
|
if not api_list:
|
|
continue
|
|
md_lines.append(f"## {category}")
|
|
md_lines.append("")
|
|
for api in sorted(api_list, key=lambda item: item.name):
|
|
source_info = f" *(from {api.source_file})*"
|
|
if api.name in self.exported_names:
|
|
surface_info = " `top-level`"
|
|
elif api.source_file.startswith("inspect/brep/"):
|
|
surface_info = " `inspection namespace`"
|
|
elif api.source_file.startswith("exporter/"):
|
|
surface_info = " `exporter namespace`"
|
|
elif api.source_file.startswith("translator/"):
|
|
surface_info = " `translator backend`"
|
|
elif api.source_file == "inverse_engineer/brep/evaluation.py":
|
|
surface_info = " `reverse-engineering evaluator`"
|
|
else:
|
|
surface_info = f" `submodule:{api.source_file.removesuffix('.py')}`"
|
|
doc_filename = api.doc_filename or f"{api.name}.md"
|
|
md_lines.append(
|
|
f"- [{api.name}]({doc_filename}){source_info}{surface_info}"
|
|
)
|
|
md_lines.append("")
|
|
|
|
return "\n".join(md_lines).rstrip() + "\n"
|
|
|
|
def _remove_stale_docs(self, output_dir: Path, generated_files: set[str]) -> int:
|
|
removed = 0
|
|
keep = set(generated_files)
|
|
keep.add("README.md")
|
|
|
|
for path in output_dir.glob("*.md"):
|
|
if path.name in keep:
|
|
continue
|
|
path.unlink()
|
|
removed += 1
|
|
|
|
return removed
|
|
|
|
@staticmethod
|
|
def _write_if_changed(file_path: Path, content: str) -> bool:
|
|
if file_path.exists() and file_path.read_text(encoding="utf-8") == content:
|
|
return False
|
|
file_path.write_text(content, encoding="utf-8")
|
|
return True
|
|
|
|
def _parse_docstring(self, docstring: str) -> Dict[str, object]:
|
|
sections = {
|
|
"description": [],
|
|
"args": [],
|
|
"returns": [],
|
|
"raises": [],
|
|
"usage": [],
|
|
"examples": [],
|
|
}
|
|
|
|
current_section = "description"
|
|
for raw_line in docstring.splitlines():
|
|
stripped = raw_line.strip()
|
|
|
|
next_section = self._map_section_header(stripped)
|
|
if next_section:
|
|
current_section = next_section
|
|
continue
|
|
|
|
sections[current_section].append(raw_line.rstrip())
|
|
|
|
parsed: Dict[str, object] = {
|
|
"description": self._collapse_paragraph_lines(sections["description"]),
|
|
"args": self._parse_args_section(sections["args"]),
|
|
"returns": self._collapse_paragraph_lines(sections["returns"]),
|
|
"raises": self._parse_raises_section(sections["raises"]),
|
|
"usage": self._collapse_paragraph_lines(sections["usage"]),
|
|
"examples": self._parse_examples_section(sections["examples"]),
|
|
}
|
|
return parsed
|
|
|
|
@staticmethod
|
|
def _map_section_header(stripped_line: str) -> str | None:
|
|
normalized = stripped_line.rstrip(":").strip().lower()
|
|
if normalized in {"args", "argument", "arguments", "parameters", "params"}:
|
|
return "args"
|
|
if normalized in {"returns", "return"}:
|
|
return "returns"
|
|
if normalized in {"raises", "raise", "exceptions", "exception"}:
|
|
return "raises"
|
|
if normalized in {"usage", "how to use"}:
|
|
return "usage"
|
|
if normalized in {"example", "examples"}:
|
|
return "examples"
|
|
return None
|
|
|
|
@staticmethod
|
|
def _collapse_paragraph_lines(lines: Iterable[str]) -> str:
|
|
filtered: List[str] = []
|
|
previous_blank = False
|
|
for line in lines:
|
|
text = line.strip()
|
|
if not text:
|
|
if not previous_blank:
|
|
filtered.append("")
|
|
previous_blank = True
|
|
continue
|
|
filtered.append(text)
|
|
previous_blank = False
|
|
return "\n".join(filtered).strip()
|
|
|
|
def _parse_args_section(self, lines: Iterable[str]) -> List[Dict[str, str]]:
|
|
args: List[Dict[str, str]] = []
|
|
current: Dict[str, str] | None = None
|
|
|
|
for raw_line in lines:
|
|
stripped = raw_line.strip()
|
|
if not stripped:
|
|
continue
|
|
|
|
if ":" in stripped and not stripped.startswith(("-", "* ")):
|
|
if current:
|
|
args.append(current)
|
|
|
|
left, right = stripped.split(":", 1)
|
|
left = left.strip()
|
|
description = right.strip()
|
|
|
|
if not left:
|
|
if current:
|
|
current["description"] = (
|
|
f"{current['description']} {stripped}".strip()
|
|
)
|
|
continue
|
|
|
|
name = left
|
|
type_info = ""
|
|
if "(" in left and ")" in left and left.endswith(")"):
|
|
open_index = left.rfind("(")
|
|
close_index = left.rfind(")")
|
|
if open_index < close_index:
|
|
name = left[:open_index].strip()
|
|
type_info = left[open_index + 1 : close_index].strip()
|
|
elif self._looks_like_type_annotation(description):
|
|
type_info = description
|
|
description = ""
|
|
|
|
current = {"name": name, "type": type_info, "description": description}
|
|
continue
|
|
|
|
if current:
|
|
current["description"] = f"{current['description']} {stripped}".strip()
|
|
|
|
if current:
|
|
args.append(current)
|
|
|
|
return args
|
|
|
|
@staticmethod
|
|
def _looks_like_type_annotation(text: str) -> bool:
|
|
stripped = text.strip()
|
|
if not stripped or stripped.endswith("."):
|
|
return False
|
|
|
|
first = stripped.split(",", 1)[0].strip()
|
|
first_word = first.split()[0] if first else ""
|
|
return first_word.startswith(
|
|
(
|
|
"int",
|
|
"float",
|
|
"str",
|
|
"bool",
|
|
"tuple",
|
|
"list",
|
|
"dict",
|
|
"Sequence",
|
|
"Iterable",
|
|
"Optional",
|
|
"Solid",
|
|
"Face",
|
|
"Wire",
|
|
"Edge",
|
|
"Vertex",
|
|
"Placement",
|
|
"Part",
|
|
"Assembly",
|
|
)
|
|
)
|
|
|
|
def _parse_raises_section(self, lines: Iterable[str]) -> List[Dict[str, str]]:
|
|
raises: List[Dict[str, str]] = []
|
|
current: Dict[str, str] | None = None
|
|
|
|
for raw_line in lines:
|
|
stripped = raw_line.strip()
|
|
if not stripped:
|
|
continue
|
|
|
|
if ":" in stripped and not stripped.startswith(("-", "* ")):
|
|
if current:
|
|
raises.append(current)
|
|
exc_name, exc_desc = stripped.split(":", 1)
|
|
current = {"type": exc_name.strip(), "description": exc_desc.strip()}
|
|
continue
|
|
|
|
if current:
|
|
current["description"] = f"{current['description']} {stripped}".strip()
|
|
|
|
if current:
|
|
raises.append(current)
|
|
|
|
return raises
|
|
|
|
@staticmethod
|
|
def _parse_examples_section(lines: Iterable[str]) -> List[str]:
|
|
blocks: List[str] = []
|
|
current: List[str] = []
|
|
|
|
for raw_line in lines:
|
|
if raw_line.strip() == "":
|
|
if current:
|
|
blocks.append(
|
|
APIDocumentGenerator._normalize_example_block(current)
|
|
)
|
|
current = []
|
|
continue
|
|
current.append(raw_line)
|
|
|
|
if current:
|
|
blocks.append(APIDocumentGenerator._normalize_example_block(current))
|
|
|
|
return [block for block in blocks if block.strip()]
|
|
|
|
@staticmethod
|
|
def _normalize_example_block(lines: List[str]) -> str:
|
|
while lines and not lines[0].strip():
|
|
lines = lines[1:]
|
|
while lines and not lines[-1].strip():
|
|
lines = lines[:-1]
|
|
if not lines:
|
|
return ""
|
|
return textwrap.dedent("\n".join(lines)).strip("\n")
|
|
|
|
def _get_function_signature(self, node: ast.FunctionDef) -> str:
|
|
params: List[str] = []
|
|
|
|
positional = list(node.args.posonlyargs) + list(node.args.args)
|
|
padded_defaults = [MISSING] * (
|
|
len(positional) - len(node.args.defaults)
|
|
) + list(node.args.defaults)
|
|
|
|
for arg, default in zip(positional, padded_defaults):
|
|
params.append(self._format_arg(arg, default))
|
|
|
|
if node.args.posonlyargs:
|
|
params.insert(len(node.args.posonlyargs), "/")
|
|
|
|
if node.args.vararg:
|
|
params.append(f"*{self._format_arg(node.args.vararg)}")
|
|
elif node.args.kwonlyargs:
|
|
params.append("*")
|
|
|
|
for kw_arg, kw_default in zip(node.args.kwonlyargs, node.args.kw_defaults):
|
|
default = kw_default if kw_default is not None else MISSING
|
|
params.append(self._format_arg(kw_arg, default))
|
|
|
|
if node.args.kwarg:
|
|
params.append(f"**{self._format_arg(node.args.kwarg)}")
|
|
|
|
returns = ""
|
|
if node.returns is not None:
|
|
returns = f" -> {self._safe_unparse(node.returns)}"
|
|
|
|
return f"def {node.name}({', '.join(params)}){returns}"
|
|
|
|
def _get_class_signature(self, node: ast.ClassDef) -> str:
|
|
init_method: ast.FunctionDef | None = None
|
|
for item in node.body:
|
|
if isinstance(item, ast.FunctionDef) and item.name == "__init__":
|
|
init_method = item
|
|
break
|
|
|
|
if init_method is None:
|
|
dataclass_fields = self._extract_dataclass_fields(node)
|
|
if dataclass_fields:
|
|
params = ", ".join(dataclass_fields)
|
|
return f"class {node.name}({params})"
|
|
return f"class {node.name}"
|
|
|
|
params: List[str] = []
|
|
|
|
positional = list(init_method.args.posonlyargs) + list(init_method.args.args)
|
|
if positional and positional[0].arg == "self":
|
|
positional = positional[1:]
|
|
padded_defaults = [MISSING] * (
|
|
len(positional) - len(init_method.args.defaults)
|
|
) + list(init_method.args.defaults)
|
|
|
|
for arg, default in zip(positional, padded_defaults):
|
|
params.append(self._format_arg(arg, default))
|
|
|
|
if init_method.args.posonlyargs:
|
|
visible_posonly_count = len(init_method.args.posonlyargs)
|
|
if init_method.args.args and init_method.args.args[0].arg == "self":
|
|
visible_posonly_count = max(0, visible_posonly_count - 1)
|
|
if visible_posonly_count > 0:
|
|
params.insert(visible_posonly_count, "/")
|
|
|
|
if init_method.args.vararg:
|
|
params.append(f"*{self._format_arg(init_method.args.vararg)}")
|
|
elif init_method.args.kwonlyargs:
|
|
params.append("*")
|
|
|
|
for kw_arg, kw_default in zip(
|
|
init_method.args.kwonlyargs, init_method.args.kw_defaults
|
|
):
|
|
default = kw_default if kw_default is not None else MISSING
|
|
params.append(self._format_arg(kw_arg, default))
|
|
|
|
if init_method.args.kwarg:
|
|
params.append(f"**{self._format_arg(init_method.args.kwarg)}")
|
|
|
|
return f"class {node.name}({', '.join(params)})"
|
|
|
|
def _format_arg(self, arg: ast.arg, default: object = MISSING) -> str:
|
|
text = arg.arg
|
|
if arg.annotation is not None:
|
|
text += f": {self._safe_unparse(arg.annotation)}"
|
|
if default is not MISSING:
|
|
text += f" = {self._safe_unparse(default)}"
|
|
return text
|
|
|
|
@staticmethod
|
|
def _safe_unparse(node: ast.AST | object) -> str:
|
|
if not isinstance(node, ast.AST):
|
|
return "..."
|
|
try:
|
|
return ast.unparse(node)
|
|
except Exception:
|
|
return "..."
|
|
|
|
def _extract_dataclass_fields(self, node: ast.ClassDef) -> List[str]:
|
|
"""Extract field signatures from a @dataclass class body.
|
|
|
|
Looks for AnnAssign nodes (annotated assignments) at class scope,
|
|
which is how dataclass fields are declared. Skips private fields
|
|
(names starting with ``_``) since they are not part of the public
|
|
constructor signature.
|
|
"""
|
|
is_dataclass = any(
|
|
isinstance(dec, ast.Name)
|
|
and dec.id == "dataclass"
|
|
or isinstance(dec, ast.Attribute)
|
|
and dec.attr == "dataclass"
|
|
or isinstance(dec, ast.Call)
|
|
and (
|
|
(isinstance(dec.func, ast.Name) and dec.func.id == "dataclass")
|
|
or (
|
|
isinstance(dec.func, ast.Attribute) and dec.func.attr == "dataclass"
|
|
)
|
|
)
|
|
for dec in node.decorator_list
|
|
)
|
|
if not is_dataclass:
|
|
return []
|
|
|
|
fields: List[str] = []
|
|
for item in node.body:
|
|
if not isinstance(item, ast.AnnAssign):
|
|
continue
|
|
if not isinstance(item.target, ast.Name):
|
|
continue
|
|
name = item.target.id
|
|
if name.startswith("_"):
|
|
continue
|
|
annotation = ""
|
|
if item.annotation is not None:
|
|
annotation = f": {self._safe_unparse(item.annotation)}"
|
|
default = ""
|
|
if item.value is not None:
|
|
default = f" = {self._safe_unparse(item.value)}"
|
|
fields.append(f"{name}{annotation}{default}")
|
|
return fields
|
|
|
|
|
|
class StdlibDocumentGenerator(APIDocumentGenerator):
|
|
"""Generate markdown docs for standard-library part factories."""
|
|
|
|
def _module_name_for(self, file_path: Path) -> str:
|
|
if file_path.parent.name == "std":
|
|
return f"std/{file_path.name}"
|
|
return file_path.name
|
|
|
|
@staticmethod
|
|
def _should_include_function(
|
|
name: str,
|
|
module_name: str,
|
|
exported_names: set[str],
|
|
) -> bool:
|
|
return not name.startswith("_")
|
|
|
|
@staticmethod
|
|
def _should_include_class(
|
|
name: str,
|
|
module_name: str,
|
|
exported_names: set[str],
|
|
) -> bool:
|
|
return False
|
|
|
|
def _import_surface_for(self, name: str, module_name: str) -> str:
|
|
if module_name == "std/bearing.py":
|
|
return (
|
|
"standard library: `import simplecadapi as scad` then "
|
|
f"`scad.std.bearing.{name}(...)`; direct submodule import: "
|
|
f"`from simplecadapi.std.bearing import {name}`"
|
|
)
|
|
if module_name == "std/gear.py":
|
|
return (
|
|
"standard library: `import simplecadapi as scad` then "
|
|
f"`scad.std.gear.{name}(...)`; direct submodule import: "
|
|
f"`from simplecadapi.std.gear import {name}`"
|
|
)
|
|
|
|
module_stem = module_name.removesuffix(".py").replace("/", ".")
|
|
return f"standard library: `from simplecadapi.{module_stem} import {name}`"
|
|
|
|
def _build_api_index_markdown(self) -> str:
|
|
categories: Dict[str, List[ApiInfo]] = {
|
|
"Bearing Assemblies": [],
|
|
"External Gears": [],
|
|
"Internal Ring Gears": [],
|
|
"Cycloidal Reducer Discs": [],
|
|
"Racks": [],
|
|
"Other Standard Parts": [],
|
|
}
|
|
|
|
for api in self.apis:
|
|
name = api.name
|
|
if api.source_file == "std/bearing.py":
|
|
categories["Bearing Assemblies"].append(api)
|
|
elif "cycloidal_disc" in name:
|
|
categories["Cycloidal Reducer Discs"].append(api)
|
|
elif "_ring_gear_" in name:
|
|
categories["Internal Ring Gears"].append(api)
|
|
elif "_rack_" in name:
|
|
categories["Racks"].append(api)
|
|
elif "_gear_" in name:
|
|
categories["External Gears"].append(api)
|
|
else:
|
|
categories["Other Standard Parts"].append(api)
|
|
|
|
md_lines: List[str] = [
|
|
"# SimpleCAD Standard Library Index",
|
|
"",
|
|
"This index includes generated docs for standard part factory functions. Use these functions first when a task needs a standard mechanical part and does not require complex custom geometry changes.",
|
|
"",
|
|
"## Import Surfaces",
|
|
"",
|
|
"- Recommended package-level module export: `import simplecadapi as scad`, then call functions through submodules such as `scad.std.gear.<function>(...)` and `scad.std.bearing.<function>(...)`.",
|
|
"- Direct submodule import is also supported, for example `from simplecadapi.std.gear import make_spur_gear_rsolid` or `from simplecadapi.std.bearing import make_ball_bearing_rassembly`.",
|
|
"",
|
|
"## Usage Guidance",
|
|
"",
|
|
"- Prefer standard-library factories for standard bearings, gears, ring gears, and racks before hand-modeling profiles with core geometry APIs.",
|
|
"- Standard parts return normal SimpleCAD shapes or product assemblies, so they can be transformed, tagged, assembled, exported, or combined with core geometry operations.",
|
|
"- Switch to core geometry APIs only when the requested standard part needs substantial custom geometry beyond the factory parameters.",
|
|
"",
|
|
]
|
|
|
|
for category, api_list in categories.items():
|
|
if not api_list:
|
|
continue
|
|
md_lines.append(f"## {category}")
|
|
md_lines.append("")
|
|
for api in sorted(api_list, key=lambda item: item.name):
|
|
doc_filename = api.doc_filename or f"{api.name}.md"
|
|
md_lines.append(
|
|
f"- [{api.name}]({doc_filename}) *(from {api.source_file})* `stdlib`"
|
|
)
|
|
md_lines.append("")
|
|
|
|
return "\n".join(md_lines).rstrip() + "\n"
|
|
|
|
|
|
def _parse_cli_args() -> argparse.Namespace:
|
|
parser = argparse.ArgumentParser(
|
|
description="SimpleCAD API markdown docs generator"
|
|
)
|
|
parser.add_argument(
|
|
"--source",
|
|
dest="sources",
|
|
action="append",
|
|
help="Source file path. Can be provided multiple times.",
|
|
)
|
|
parser.add_argument(
|
|
"--output-dir",
|
|
dest="output_dirs",
|
|
action="append",
|
|
help="Output directory path. Can be provided multiple times.",
|
|
)
|
|
parser.add_argument(
|
|
"--no-clean",
|
|
action="store_true",
|
|
help="Keep stale markdown API docs instead of deleting them.",
|
|
)
|
|
parser.add_argument(
|
|
"--quiet",
|
|
action="store_true",
|
|
help="Reduce console output.",
|
|
)
|
|
return parser.parse_args()
|
|
|
|
|
|
def _resolve_source_files(
|
|
cli_sources: Sequence[str] | None,
|
|
module_file: Path | str | None = None,
|
|
) -> List[Path]:
|
|
if cli_sources:
|
|
return [Path(item).resolve() for item in cli_sources]
|
|
package_root = _package_root_from(module_file)
|
|
return [path.resolve() for path in _default_source_files(package_root)]
|
|
|
|
|
|
def _resolve_output_dirs(
|
|
cli_output_dirs: Sequence[str] | None,
|
|
module_file: Path | str | None = None,
|
|
) -> List[Path]:
|
|
if cli_output_dirs:
|
|
return [Path(item).resolve() for item in cli_output_dirs]
|
|
return [path.resolve() for path in _default_output_dirs(module_file)]
|
|
|
|
|
|
def _resolve_stdlib_source_files(
|
|
cli_sources: Sequence[str] | None,
|
|
module_file: Path | str | None = None,
|
|
) -> List[Path]:
|
|
if cli_sources:
|
|
return [Path(item).resolve() for item in cli_sources]
|
|
package_root = _package_root_from(module_file)
|
|
return [path.resolve() for path in _default_stdlib_source_files(package_root)]
|
|
|
|
|
|
def _resolve_stdlib_output_dirs(
|
|
cli_output_dirs: Sequence[str] | None,
|
|
module_file: Path | str | None = None,
|
|
) -> List[Path]:
|
|
if cli_output_dirs:
|
|
return [Path(item).resolve() for item in cli_output_dirs]
|
|
return [path.resolve() for path in _default_stdlib_output_dirs(module_file)]
|
|
|
|
|
|
def main() -> None:
|
|
args = _parse_cli_args()
|
|
source_files = _resolve_source_files(args.sources)
|
|
output_dirs = _resolve_output_dirs(args.output_dirs)
|
|
generate_default_stdlib_docs = not args.sources and not args.output_dirs
|
|
|
|
generator = APIDocumentGenerator(
|
|
source_files=source_files,
|
|
output_dirs=output_dirs,
|
|
clean_stale=not args.no_clean,
|
|
quiet=args.quiet,
|
|
)
|
|
|
|
apis = generator.extract_apis()
|
|
if not apis:
|
|
print("没有找到任何带有docstring的API函数")
|
|
return
|
|
|
|
generator.generate_markdown_docs()
|
|
|
|
stdlib_api_count = 0
|
|
if generate_default_stdlib_docs:
|
|
stdlib_generator = StdlibDocumentGenerator(
|
|
source_files=_resolve_stdlib_source_files(None),
|
|
output_dirs=_resolve_stdlib_output_dirs(None),
|
|
clean_stale=not args.no_clean,
|
|
quiet=args.quiet,
|
|
)
|
|
stdlib_apis = stdlib_generator.extract_apis()
|
|
stdlib_api_count = len(stdlib_apis)
|
|
if stdlib_apis:
|
|
stdlib_generator.generate_markdown_docs()
|
|
|
|
if not args.quiet:
|
|
print("\n✅ 文档生成完成!")
|
|
print(f"📄 共处理 {len(apis)} 个API")
|
|
if generate_default_stdlib_docs:
|
|
print(f"📦 共处理 {stdlib_api_count} 个标准库API")
|
|
print("📁 输出目录:")
|
|
for path in output_dirs:
|
|
print(f" - {path}")
|
|
if generate_default_stdlib_docs:
|
|
for path in _resolve_stdlib_output_dirs(None):
|
|
print(f" - {path}")
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|