Files
make-cad/test/test_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

689 lines
27 KiB
Python

import importlib.util
import sys
import tempfile
import unittest
from pathlib import Path
MODULE_PATH = (
Path(__file__).resolve().parents[1] / "tools/auto_docs_gen.py"
)
MODULE_SPEC = importlib.util.spec_from_file_location(
"simplecadapi_auto_docs_gen",
MODULE_PATH,
)
if MODULE_SPEC is None or MODULE_SPEC.loader is None:
raise RuntimeError(f"Unable to load module spec for {MODULE_PATH}")
auto_docs_gen = importlib.util.module_from_spec(MODULE_SPEC)
sys.modules[MODULE_SPEC.name] = auto_docs_gen
MODULE_SPEC.loader.exec_module(auto_docs_gen)
class TestAutoDocsGenPathResolution(unittest.TestCase):
def test_resolve_source_files_from_repo_checkout(self):
with tempfile.TemporaryDirectory() as tmp_dir:
project_root = Path(tmp_dir)
(project_root / "pyproject.toml").write_text(
"[project]\nname = 'demo'\n",
encoding="utf-8",
)
module_file = project_root / "tools/auto_docs_gen.py"
module_file.parent.mkdir(parents=True, exist_ok=True)
module_file.write_text("", encoding="utf-8")
resolved = auto_docs_gen._resolve_source_files(
None, module_file=module_file
)
package_root = project_root / "src/simplecadapi"
expected = [
(package_root / name).resolve()
for name in auto_docs_gen.DEFAULT_SOURCE_FILENAMES
]
self.assertEqual(resolved, expected)
def test_resolve_source_files_outside_repo_fails_loud(self):
with tempfile.TemporaryDirectory() as tmp_dir:
module_file = Path(tmp_dir) / "auto_docs_gen.py"
module_file.write_text("", encoding="utf-8")
with self.assertRaises(FileNotFoundError):
auto_docs_gen._resolve_source_files(None, module_file=module_file)
def test_resolve_output_dirs_from_source_checkout_uses_repo_docs(self):
with tempfile.TemporaryDirectory() as tmp_dir:
project_root = Path(tmp_dir)
(project_root / "pyproject.toml").write_text(
"[project]\nname = 'demo'\n",
encoding="utf-8",
)
module_file = project_root / "tools/auto_docs_gen.py"
module_file.parent.mkdir(parents=True, exist_ok=True)
module_file.write_text("", encoding="utf-8")
resolved = auto_docs_gen._resolve_output_dirs(None, module_file=module_file)
self.assertEqual(
resolved,
[(project_root / "docs/skill/references/docs/api").resolve()],
)
def test_default_source_files_include_v2_public_modules(self):
with tempfile.TemporaryDirectory() as tmp_dir:
package_root = Path(tmp_dir) / "src/simplecadapi"
package_root.mkdir(parents=True, exist_ok=True)
backend_root = package_root / "translator/freecad_translator"
backend_root.mkdir(parents=True)
(backend_root / "api.py").write_text("", encoding="utf-8")
(backend_root / "translator.py").write_text("", encoding="utf-8")
(backend_root / "types.py").write_text("", encoding="utf-8")
resolved = auto_docs_gen._default_source_files(package_root)
resolved_names = [
path.relative_to(package_root).as_posix() for path in resolved
]
self.assertIn("recording/serializer.py", resolved_names)
self.assertIn("recording/graph.py", resolved_names)
self.assertIn("params/expr.py", resolved_names)
self.assertIn("params/tolerance.py", resolved_names)
self.assertIn("sketch.py", resolved_names)
self.assertIn("math.py", resolved_names)
self.assertIn("translator/freecad_translator/api.py", resolved_names)
self.assertIn(
"translator/freecad_translator/translator.py",
resolved_names,
)
self.assertIn(
"translator/freecad_translator/types.py",
resolved_names,
)
self.assertIn("inspect/brep/inspect.py", resolved_names)
self.assertIn("inspect/brep/manufacturing.py", resolved_names)
self.assertIn("inspect/brep/queries.py", resolved_names)
self.assertIn("exporter/mjcf.py", resolved_names)
def test_default_source_files_include_cache_build_public_surface(self):
with tempfile.TemporaryDirectory() as tmp_dir:
package_root = Path(tmp_dir) / "src/simplecadapi"
package_root.mkdir(parents=True, exist_ok=True)
resolved = auto_docs_gen._default_source_files(package_root)
resolved_names = [
path.relative_to(package_root).as_posix() for path in resolved
]
self.assertIn("build/part_builder.py", resolved_names)
self.assertIn("build/assembly_builder.py", resolved_names)
self.assertIn("build/dependencies.py", resolved_names)
self.assertIn("build/results.py", resolved_names)
self.assertIn("product/capture.py", resolved_names)
self.assertIn("cache/policy.py", resolved_names)
self.assertIn("cache/store.py", resolved_names)
def test_real_cache_build_sources_document_only_top_level_surface(self):
with tempfile.TemporaryDirectory() as tmp_dir:
generator = auto_docs_gen.APIDocumentGenerator(
source_files=auto_docs_gen._default_source_files(
Path(__file__).resolve().parents[1] / "src/simplecadapi"
),
output_dirs=[Path(tmp_dir) / "docs/api"],
quiet=True,
)
names = {api.name for api in generator.extract_apis()}
for name in (
"capture",
"CaptureResult",
"assemble",
"file_input",
"part",
"AssemblyBuildResult",
"AssemblySolveReport",
"CachePolicy",
"CacheReport",
"ContentAddressedStore",
"ProductMJCFExportReport",
"export_product_package_to_mjcf",
):
self.assertIn(name, names)
self.assertNotIn("snapshot_file_inputs", names)
self.assertNotIn("OperationCacheReport", names)
self.assertNotIn("operation_cache_scope", names)
self.assertNotIn("operation_cache_report", names)
def test_inspect_brep_api_docs_use_inspection_namespace(self):
class InspectionDocGenerator(auto_docs_gen.APIDocumentGenerator):
def _module_name_for(self, file_path):
return "inspect/brep/inspect.py"
with tempfile.TemporaryDirectory() as tmp_dir:
tmp_path = Path(tmp_dir)
package_root = tmp_path / "simplecadapi"
source_file = package_root / "inspect/brep/inspect.py"
source_file.parent.mkdir(parents=True)
(package_root / "__init__.py").write_text(
"__all__ = ['inspect']\n",
encoding="utf-8",
)
source_file.write_text(
"def inspect_step_rsummary(path: str) -> dict:\n"
' """Inspect one STEP summary."""\n'
" return {}\n",
encoding="utf-8",
)
output_dir = tmp_path / "docs/api"
generator = InspectionDocGenerator(
source_files=[source_file],
output_dirs=[output_dir],
quiet=True,
)
generator.extract_apis()
generator.generate_markdown_docs()
readme = (output_dir / "README.md").read_text(encoding="utf-8")
page = (output_dir / "inspect_step_rsummary.md").read_text(encoding="utf-8")
self.assertIn("## STEP/BREP Inspection", readme)
self.assertIn("`inspection namespace`", readme)
self.assertIn("from simplecadapi.inspect import brep", page)
self.assertIn("unavailable inside GraphSession", page)
def test_real_drawing_sources_export_namespace_and_acceptance_docs(self):
project_root = MODULE_PATH.parents[1]
source_root = project_root / "src/simplecadapi"
sources = [
path
for path in auto_docs_gen._default_source_files(source_root)
if path.parent == source_root / "inspect/drawing"
]
with tempfile.TemporaryDirectory() as tmp_dir:
output = Path(tmp_dir)
generator = auto_docs_gen.APIDocumentGenerator(
source_files=sources, output_dirs=[output], quiet=True
)
apis = generator.extract_apis()
generator.generate_markdown_docs()
names = {api.name for api in apis}
self.assertTrue(
{
"DrawingSectionDimensions",
"DrawingText",
"extract_drawing_primitives_rstrokes",
"measure_model_section_rdimensions",
"validate_section_annotations_rreport",
"assess_dimension_rverdict",
}
<= names
)
self.assertNotIn("section_geometry", names)
self.assertNotIn("fit_circle_diagnostics", names)
for api in apis:
self.assertIn("drawing-inspection namespace", api.import_surface)
self.assertIn("unavailable inside GraphSession", api.import_surface)
self.assertIn(
"## Drawing Inspection",
(output / "README.md").read_text(encoding="utf-8"),
)
measure = (output / "measure_model_section_rdimensions.md").read_text(
encoding="utf-8"
)
self.assertIn("section_checks", measure)
self.assertIn("unknown", measure.lower())
def test_evaluator_api_docs_preserve_schemas_units_and_trust_boundaries(self):
class EvaluationDocGenerator(auto_docs_gen.APIDocumentGenerator):
def _module_name_for(self, file_path):
return "inverse_engineer/brep/evaluation.py"
project_root = MODULE_PATH.parents[1]
source_file = (
project_root / "src/simplecadapi/inverse_engineer/brep/evaluation.py"
)
with tempfile.TemporaryDirectory() as tmp_dir:
output_dir = Path(tmp_dir) / "docs/api"
generator = EvaluationDocGenerator(
source_files=[source_file],
output_dirs=[output_dir],
quiet=True,
)
generator.extract_apis()
generator.generate_markdown_docs()
readme = (output_dir / "README.md").read_text(encoding="utf-8")
bundle = (output_dir / "run_comparison_bundle.md").read_text(
encoding="utf-8"
)
config = (output_dir / "EvaluationConfig.md").read_text(encoding="utf-8")
classify = (output_dir / "classify_benchmark_result.md").read_text(
encoding="utf-8"
)
section = (output_dir / "SectionEvaluationConfig.md").read_text(
encoding="utf-8"
)
self.assertIn("## Reconstruction Evaluation", readme)
self.assertIn("`reverse-engineering evaluator`", readme)
self.assertIn("from simplecadapi.inverse_engineer.brep import", bundle)
self.assertNotIn("top-level:", bundle)
self.assertIn("Report schemas and units", bundle)
self.assertIn("cubic millimetres", bundle)
self.assertIn("checks.hard_gate", bundle)
self.assertIn(
"diagnostic, never equality proof",
" ".join(bundle.split()),
)
self.assertIn("diagnostics and never affect classification", bundle)
self.assertIn("status ``completed``", bundle)
self.assertIn("``gate_passed=None``", bundle)
self.assertIn("strict bidirectional", bundle)
self.assertIn("non-fuzzy bidirectional Cut residual volumes", bundle)
self.assertIn("mass-property comparison", bundle)
for deprecated in (
"global_max_bbox_delta",
"global_max_centroid_distance",
"global_max_relative_volume_error",
"global_max_relative_area_error",
"boundary_max_hausdorff",
"boundary_max_p95",
):
self.assertIn(deprecated, config)
self.assertIn("deprecated compatibility inputs and are ignored", config)
self.assertIn("strict_material_tolerance", config)
self.assertIn("boundary_linear_deflection", config)
self.assertIn("boundary_max_samples", config)
self.assertIn("strict_geometric_tolerance", config)
self.assertIn("unmodified, process-local result", classify)
self.assertIn("ignored by classification", classify)
self.assertIn("at least one unique face", classify)
self.assertIn(
"not just a claimed stage status",
" ".join(classify.split()),
)
self.assertIn("bounded diagnostic section probe", section)
self.assertIn("not acceptance gates", section)
self.assertIn("require_nonempty", section)
self.assertIn("max_hausdorff", section)
self.assertIn("max_relative_area_error", section)
self.assertIn("deprecated compatibility inputs", section)
self.assertIn("do not affect stage status", section)
def test_persistence_api_docs_distinguish_roundtrip_from_target_similarity(self):
class PersistenceDocGenerator(auto_docs_gen.APIDocumentGenerator):
def _module_name_for(self, file_path):
return "inspect/brep/persistence.py"
project_root = MODULE_PATH.parents[1]
source_file = project_root / "src/simplecadapi/inspect/brep/persistence.py"
with tempfile.TemporaryDirectory() as tmp_dir:
output_dir = Path(tmp_dir) / "docs/api"
generator = PersistenceDocGenerator(
source_files=[source_file],
output_dirs=[output_dir],
quiet=True,
)
generator.extract_apis()
generator.generate_markdown_docs()
persistence = (
output_dir / "validate_step_roundtrip_rdescriptor.md"
).read_text(encoding="utf-8")
self.assertIn("candidate-before/after volume and surface-area", persistence)
self.assertIn("STEP serialization integrity checks", persistence)
self.assertIn("not candidate-to-target", persistence)
def test_manufacturing_module_generates_public_api_pages(self):
project_root = Path(__file__).resolve().parents[1]
source_file = (
project_root / "src/simplecadapi/inspect/brep/manufacturing.py"
)
with tempfile.TemporaryDirectory() as tmp_dir:
output_dir = Path(tmp_dir) / "docs/api"
generator = auto_docs_gen.APIDocumentGenerator(
source_files=[source_file],
output_dirs=[output_dir],
quiet=True,
)
generator.extract_apis()
generator.generate_markdown_docs()
readme = (output_dir / "README.md").read_text(encoding="utf-8")
self.assertTrue(
(output_dir / "inspect_manufacturing_hints_rdescriptor.md").exists()
)
self.assertTrue(
(output_dir / "render_manufacturing_hints_rpath.md").exists()
)
self.assertIn("inspect_manufacturing_hints_rdescriptor", readme)
self.assertIn("render_manufacturing_hints_rpath", readme)
renderer_page = (
output_dir / "render_manufacturing_hints_rpath.md"
).read_text(encoding="utf-8")
self.assertNotIn("report:", renderer_page)
def test_default_stdlib_source_files_include_standard_modules(self):
with tempfile.TemporaryDirectory() as tmp_dir:
package_root = Path(tmp_dir) / "src/simplecadapi"
package_root.mkdir(parents=True, exist_ok=True)
resolved = auto_docs_gen._default_stdlib_source_files(package_root)
self.assertEqual(
resolved,
[
package_root / "std/bearing.py",
package_root / "std/gear.py",
],
)
def test_resolve_stdlib_output_dirs_from_source_checkout_uses_repo_docs(self):
with tempfile.TemporaryDirectory() as tmp_dir:
project_root = Path(tmp_dir)
(project_root / "pyproject.toml").write_text(
"[project]\nname = 'demo'\n",
encoding="utf-8",
)
module_file = project_root / "tools/auto_docs_gen.py"
module_file.parent.mkdir(parents=True, exist_ok=True)
module_file.write_text("", encoding="utf-8")
resolved = auto_docs_gen._resolve_stdlib_output_dirs(
None,
module_file=module_file,
)
self.assertEqual(
resolved,
[(project_root / "docs/skill/references/docs/stdlib").resolve()],
)
class TestAutoDocsGenExtraction(unittest.TestCase):
def test_extract_apis_from_v2_public_modules(self):
with tempfile.TemporaryDirectory() as tmp_dir:
tmp_path = Path(tmp_dir)
(tmp_path / "pkg").mkdir()
(tmp_path / "pkg" / "__init__.py").write_text("", encoding="utf-8")
(tmp_path / "pkg" / "recording").mkdir()
(tmp_path / "pkg" / "recording" / "__init__.py").write_text(
"", encoding="utf-8"
)
source_file = tmp_path / "pkg" / "recording" / "serializer.py"
source_file.write_text(
"""
def export_model_json(session, indent=2):
\"\"\"Export the canonical 2.0 model seed JSON.\"\"\"
return \"{}\"
def _internal_helper():
\"\"\"Should not be documented.\"\"\"
return None
""".strip()
+ "\n",
encoding="utf-8",
)
output_dir = tmp_path / "docs/api"
generator = auto_docs_gen.APIDocumentGenerator(
source_files=[source_file],
output_dirs=[output_dir],
quiet=True,
)
apis = generator.extract_apis()
self.assertEqual([api.name for api in apis], ["export_model_json"])
def test_generate_markdown_includes_v2_model_api_entry(self):
with tempfile.TemporaryDirectory() as tmp_dir:
tmp_path = Path(tmp_dir)
(tmp_path / "pkg").mkdir()
(tmp_path / "pkg" / "__init__.py").write_text("", encoding="utf-8")
(tmp_path / "pkg" / "recording").mkdir()
(tmp_path / "pkg" / "recording" / "__init__.py").write_text(
"", encoding="utf-8"
)
source_file = tmp_path / "pkg" / "recording" / "serializer.py"
source_file.write_text(
"""
def export_model_json(session, indent=2):
\"\"\"Export the canonical 2.0 model seed JSON.
Args:
session: Recorded graph session.
indent: JSON indentation level.
Returns:
JSON string representation.
\"\"\"
return \"{}\"
""".strip()
+ "\n",
encoding="utf-8",
)
output_dir = tmp_path / "docs/api"
generator = auto_docs_gen.APIDocumentGenerator(
source_files=[source_file],
output_dirs=[output_dir],
quiet=True,
)
generator.extract_apis()
generator.generate_markdown_docs()
readme = (output_dir / "README.md").read_text(encoding="utf-8")
page = (output_dir / "export_model_json.md").read_text(encoding="utf-8")
self.assertIn("[export_model_json](export_model_json.md)", readme)
self.assertIn("def export_model_json(session, indent = 2)", page)
self.assertIn("Export the canonical 2.0 model seed JSON.", page)
def test_generate_markdown_avoids_case_insensitive_filename_collisions(self):
with tempfile.TemporaryDirectory() as tmp_dir:
tmp_path = Path(tmp_dir)
(tmp_path / "pkg").mkdir()
(tmp_path / "pkg" / "__init__.py").write_text("", encoding="utf-8")
(tmp_path / "pkg" / "params").mkdir()
(tmp_path / "pkg" / "params" / "__init__.py").write_text(
"", encoding="utf-8"
)
source_file = tmp_path / "pkg" / "params" / "expr.py"
source_file.write_text(
"""
class Const:
\"\"\"Constant node.\"\"\"
def const(value):
\"\"\"Constant constructor.\"\"\"
return value
""".strip()
+ "\n",
encoding="utf-8",
)
output_dir = tmp_path / "docs/api"
generator = auto_docs_gen.APIDocumentGenerator(
source_files=[source_file],
output_dirs=[output_dir],
quiet=True,
)
generator.extract_apis()
generator.generate_markdown_docs()
readme = (output_dir / "README.md").read_text(encoding="utf-8")
self.assertTrue((output_dir / "Const.md").exists())
self.assertTrue((output_dir / "const_function.md").exists())
self.assertIn("[Const](Const.md)", readme)
self.assertIn("[const](const_function.md)", readme)
def test_generate_markdown_includes_math_helper_category(self):
with tempfile.TemporaryDirectory() as tmp_dir:
tmp_path = Path(tmp_dir)
init_file = tmp_path / "__init__.py"
init_file.write_text(
"__all__ = ['BSplineFitResult', 'fit_cubic_bspline_control_points']\n",
encoding="utf-8",
)
source_file = tmp_path / "math.py"
source_file.write_text(
'''
class BSplineFitResult:
"""B-spline fitting result."""
def fit_cubic_bspline_control_points(sample_points, *, tolerance=1e-3):
"""Fit sampled points to cubic B-spline controls."""
return BSplineFitResult()
'''.strip()
+ "\n",
encoding="utf-8",
)
output_dir = tmp_path / "docs/api"
generator = auto_docs_gen.APIDocumentGenerator(
source_files=[source_file],
output_dirs=[output_dir],
quiet=True,
)
generator.extract_apis()
generator.generate_markdown_docs()
readme = (output_dir / "README.md").read_text(encoding="utf-8")
self.assertIn("## Math Helpers", readme)
self.assertIn("[BSplineFitResult](BSplineFitResult.md)", readme)
self.assertIn(
"[fit_cubic_bspline_control_points](fit_cubic_bspline_control_points.md)",
readme,
)
def test_generate_markdown_includes_top_level_exported_operations_class(self):
with tempfile.TemporaryDirectory() as tmp_dir:
tmp_path = Path(tmp_dir)
(tmp_path / "__init__.py").write_text(
"__all__ = ['SurfaceSettings']\n", encoding="utf-8"
)
source_file = tmp_path / "ql.py"
source_file.write_text(
'''
from dataclasses import dataclass
@dataclass(frozen=True)
class SurfaceSettings:
"""Surface construction settings."""
degree: int = 3
'''.strip()
+ "\n",
encoding="utf-8",
)
output_dir = tmp_path / "docs/api"
generator = auto_docs_gen.APIDocumentGenerator(
source_files=[source_file], output_dirs=[output_dir], quiet=True
)
generator.extract_apis()
generator.generate_markdown_docs()
readme = (output_dir / "README.md").read_text(encoding="utf-8")
page = (output_dir / "SurfaceSettings.md").read_text(encoding="utf-8")
self.assertIn("[SurfaceSettings](SurfaceSettings.md)", readme)
self.assertIn("class SurfaceSettings(degree: int = 3)", page)
self.assertIn("from simplecadapi import SurfaceSettings", page)
def test_generate_markdown_includes_physical_units_category(self):
with tempfile.TemporaryDirectory() as tmp_dir:
tmp_path = Path(tmp_dir)
(tmp_path / "pkg" / "params").mkdir(parents=True)
init_file = tmp_path / "pkg" / "__init__.py"
init_file.write_text(
"__all__ = ['Dimension', 'convert_value']\n", encoding="utf-8"
)
(tmp_path / "pkg" / "params" / "__init__.py").write_text(
"", encoding="utf-8"
)
source_file = tmp_path / "pkg" / "params" / "units.py"
source_file.write_text(
'''
class Dimension:
"""Physical dimension."""
def convert_value(value, from_unit, to_unit):
"""Convert compatible units."""
return value
'''.strip()
+ "\n",
encoding="utf-8",
)
output_dir = tmp_path / "docs/api"
generator = auto_docs_gen.APIDocumentGenerator(
source_files=[source_file], output_dirs=[output_dir], quiet=True
)
generator.extract_apis()
generator.generate_markdown_docs()
readme = (output_dir / "README.md").read_text(encoding="utf-8")
self.assertIn("## Physical Units", readme)
self.assertIn("[Dimension](Dimension.md)", readme)
self.assertIn("[convert_value](convert_value.md)", readme)
def test_generate_stdlib_markdown_uses_stdlib_index_and_import_surface(self):
with tempfile.TemporaryDirectory() as tmp_dir:
tmp_path = Path(tmp_dir)
source_dir = tmp_path / "std"
source_dir.mkdir()
source_file = source_dir / "gear.py"
source_file.write_text(
'''
def make_spur_gear_rsolid(n_teeth: int, module: float):
"""Create a test spur gear.
Parameters
----------
n_teeth : int
Number of teeth.
module : float
Gear module.
"""
return None
def _private_helper():
"""Should not be documented."""
return None
'''.strip()
+ "\n",
encoding="utf-8",
)
output_dir = tmp_path / "docs/stdlib"
generator = auto_docs_gen.StdlibDocumentGenerator(
source_files=[source_file],
output_dirs=[output_dir],
quiet=True,
)
generator.extract_apis()
generator.generate_markdown_docs()
readme = (output_dir / "README.md").read_text(encoding="utf-8")
page = (output_dir / "make_spur_gear_rsolid.md").read_text(encoding="utf-8")
self.assertIn("# SimpleCAD Standard Library Index", readme)
self.assertIn("[make_spur_gear_rsolid](make_spur_gear_rsolid.md)", readme)
self.assertIn("scad.std.gear.make_spur_gear_rsolid", page)
self.assertIn("**Type**: `int`", page)
self.assertNotIn("_private_helper", readme)
if __name__ == "__main__":
unittest.main()