Skip to main content

manuscript

Version: v1.3.0 | Status: Active | Last Updated: July 2026

Overview​

The manuscript module computes manuscript token variables from real repository state and generates the publication-quality figures used in the Codomyrmex paper. The package is the single implementation authority; the project-local scripts are thin command-line entry points.

Key Components​

ComponentFilePurpose
compute_variables()variables.pyCompute manuscript token variables from repo state
inject_manuscript_variables()variables.pyHydrate through the pinned template entrypoint, with an explicit strict local successor for standalone clones
validate_variable_contract()variables.pyDetect undefined, unresolved, stale, and unused publication tokens
figures.main()figures/orchestrator.pyRun every figure generator
FIGURES registryfigures/__init__.pyRegistry of fig_*() generators

The generator writes output/data/manuscript_variables.json and the machine-readable output/data/manuscript_variable_manifest.json. Every active prose token, table value, caption, figure annotation, and accessibility string must resolve from that snapshot or be explicitly classified as mathematical notation, a citation year, or provenance metadata. The manifest is a contract check, not evidence that a scientific hypothesis has been supported.

The hydration contract is recorded in docs/manuscript/config.yaml. When the adjacent clean checkout of docxology/template matches the pinned revision, the generator calls infrastructure.rendering.manuscript_injection.write_resolved_manuscript_tree. If that checkout is unavailable, the project-local strict renderer is used and the fallback is recorded rather than being presented as the canonical template.

Quick Start​

from pathlib import Path

from codomyrmex.manuscript.variables import (
    compute_variables,
    inject_manuscript_variables,
)
from codomyrmex.manuscript.figures import main as generate_all_figures

project_root = Path.cwd()  # run this example from the repository root
config_path = project_root / "docs/manuscript/config.yaml"
manuscript_dir = project_root / "docs/manuscript"
output_dir = project_root / "output/manuscript"
variables = compute_variables(config_path, project_root)
inject_manuscript_variables(manuscript_dir, output_dir, variables)
generate_all_figures()

For a read-only check of an existing snapshot:

uv run python scripts/validate_manuscript_contract.py

Validation​

uv run pytest tests/unit/manuscript/ -q
uv run ruff check src/codomyrmex/manuscript
uv run ty check --output-format concise src/codomyrmex/manuscript