Files
make-cad/tools/auto_docs_gen.py
T
liuyu 9caa2caa3a feat(drawing): integrate PDF reconstruction and evidence validation
Add the drawing inspection namespace and its parser, calibration, section and
independent acceptance dependencies on the current dev architecture.

Protect input BREP during material fusion and sectioning. Bind dimensions,
annotations and visual reviews to source identities and measured geometry.
Connect the workflow and generated API docs to all seven skill build targets.
Make standalone verifier tests work with the pytest console entry point.

Validation: 186 drawing, documentation, skill-target and public API tests;
16 non-render BREP query tests; compileall and skillbuild --check.
2026-09-11 13:36:27 +08:00

1413 lines
50 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",
"inspect/drawing/calibrate.py",
"inspect/drawing/geometry.py",
"inspect/drawing/evidence.py",
"inspect/drawing/preflight.py",
"inspect/drawing/render.py",
"inspect/drawing/section.py",
"inspect/drawing/summary.py",
"inspect/drawing/text.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",
"inspect/drawing/calibrate.py",
"inspect/drawing/geometry.py",
"inspect/drawing/evidence.py",
"inspect/drawing/preflight.py",
"inspect/drawing/render.py",
"inspect/drawing/section.py",
"inspect/drawing/summary.py",
"inspect/drawing/text.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.startswith("inspect/drawing/"):
return name.endswith(
(
"_rcalibration",
"_rdimensions",
"_rmeasurements",
"_rpath",
"_rrecord",
"_rreport",
"_rstrokes",
"_rsummary",
"_rwords",
"_rverdict",
)
)
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.startswith("inspect/drawing/"):
return name in {
"DrawingCalibration",
"DrawingMeasurements",
"DrawingSectionDimensions",
"DrawingStrokes",
"DrawingSummary",
"DrawingText",
}
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("inspect/drawing/"):
return (
"drawing-inspection namespace: "
"`from simplecadapi.inspect import drawing` "
f"then `drawing.{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": [],
"Drawing 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("inspect/drawing/"):
categories["Drawing 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 `drawing-inspection namespace` are available through `simplecadapi.inspect.drawing` 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("inspect/drawing/"):
surface_info = " `drawing-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()