John McCardle
626d5ae708
Static-analysis tool for the pre-1.0 API freeze: walks src/**/*.cpp with
tree-sitter-cpp, locates every PyMethodDef and PyGetSetDef array initializer,
and classifies each entry's docstring slot as MACRO / RAW_STRING / NULL /
MISSING. The MACRO classification (MCRF_METHOD or MCRF_PROPERTY from
McRFPy_Doc.h) is the project's compliance target; raw string literals and
NULL docs predate the macro system and need migration before the 1.0 freeze.
Features:
- Per-file table (file:line, array, entry, classification) plus summary
footer with totals, per-kind breakdown, % MACRO compliance, and a
ranked list of the worst-offender files.
- --strict exits nonzero when any non-MACRO entries are present (CI use).
- --quiet suppresses per-file tables and prints only the summary.
- --paths PATH [PATH ...] limits the scan to specific files / directories.
- Sentinel terminator entries ({NULL}, {0}) are filtered out.
- Concatenated string literals and parenthesized expressions are handled.
Dependencies live in a project-local .venv-audit (added to .gitignore) so
no system Python pollution. tools/generate_all_docs.sh now invokes the
auditor at the end (informational, no --strict) so doc regeneration
surfaces compliance drift alongside the generated docs themselves.
Initial baseline on the current tree: 755 entries scanned, 340 MACRO
compliant (45.0%). Top offenders: UIEntity.cpp (51), 3d/PyVoxelGrid.cpp
(36), 3d/Viewport3D.cpp (31), UIGridPyProperties.cpp (30),
3d/Entity3D.cpp (28).
Refs pre-1.0 documentation freeze.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
49 lines
1.9 KiB
Bash
Executable file
49 lines
1.9 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
|
|
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
|