John McCardle
1362d5155d
generate_all_docs.sh now runs check_frozen_docstrings.sh as a hard gate after doc generation: the frozen (non-3D) binding surface must stay 100% MCRF_* macro compliant, or the doc build fails. This is the docstring analog of the API-surface snapshot test -- it prevents future raw docstrings from silently regressing the frozen 1.0 documentation contract. Skipped gracefully when .venv-audit is absent; experimental src/3d/ bindings remain exempt. Refs #314 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
57 lines
2.3 KiB
Bash
Executable file
57 lines
2.3 KiB
Bash
Executable file
#!/bin/bash
|
|
set -e # Exit on any error
|
|
|
|
echo "=== McRogueFace Documentation Generation ==="
|
|
|
|
# Verify build exists
|
|
if [ ! -f "./build/mcrogueface" ]; then
|
|
echo "ERROR: build/mcrogueface not found. Run 'make' first."
|
|
exit 1
|
|
fi
|
|
|
|
# Generate API docs (HTML + Markdown)
|
|
echo "Generating API documentation..."
|
|
./build/mcrogueface --headless --exec tools/generate_dynamic_docs.py
|
|
|
|
# Generate type stubs (using v2 - manually maintained high-quality stubs)
|
|
echo "Generating type stubs..."
|
|
./build/mcrogueface --headless --exec tools/generate_stubs_v2.py
|
|
|
|
# Generate man page
|
|
echo "Generating man page..."
|
|
./tools/generate_man_page.sh
|
|
|
|
echo "=== Documentation generation complete ==="
|
|
echo " HTML: docs/api_reference_dynamic.html"
|
|
echo " Markdown: docs/API_REFERENCE_DYNAMIC.md"
|
|
echo " Man page: docs/mcrfpy.3"
|
|
echo " Stubs: stubs/mcrfpy.pyi"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Static-analysis audit: report MCRF_METHOD / MCRF_PROPERTY macro compliance
|
|
# across every PyMethodDef / PyGetSetDef array in src/. This is informational
|
|
# only (no --strict) so it cannot break the doc build, but the summary makes
|
|
# pre-1.0 documentation drift visible alongside doc generation.
|
|
#
|
|
# Requires the .venv-audit virtual environment with tree-sitter +
|
|
# tree-sitter-cpp installed. The audit is skipped silently if absent so
|
|
# contributors without the venv aren't blocked.
|
|
# ---------------------------------------------------------------------------
|
|
if [ -x "./.venv-audit/bin/python3" ] && [ -f "./tools/audit_pymethoddef.py" ]; then
|
|
echo ""
|
|
echo "=== PyMethodDef / PyGetSetDef Macro Compliance Audit ==="
|
|
./.venv-audit/bin/python3 ./tools/audit_pymethoddef.py --quiet || true
|
|
|
|
# Hard gate (#314 F15): the frozen (non-3D) binding surface must stay 100%
|
|
# MCRF_* macro compliant. This fails the doc build if any frozen file
|
|
# regresses to a raw docstring -- the docstring analog of the API-surface
|
|
# snapshot test. Experimental src/3d/ bindings are exempt.
|
|
echo ""
|
|
echo "=== Frozen docstring gate (strict) ==="
|
|
./tools/check_frozen_docstrings.sh
|
|
elif [ -f "./tools/audit_pymethoddef.py" ]; then
|
|
echo ""
|
|
echo "(skipping audit_pymethoddef.py: .venv-audit not found - run"
|
|
echo " 'python3 -m venv .venv-audit && .venv-audit/bin/pip install"
|
|
echo " tree-sitter tree-sitter-cpp' to enable)"
|
|
fi
|