Skip to content

Rebuild and contribute

The reference consumes Echopy's captured/enriched Python sources and adjacent stubs. It renders as the actual fontlab, fontgate, fontpr, PythonQt.* namespaces. Runtime inspection is disabled throughout normal documentation builds.

Source checkout mode uses sibling ecosystem repositories. Installed artifact mode selects one provisioned Python package directory with FONTLAB_API_SOURCE_ROOT. Private sources are provisioned using authenticated GitHub tooling, without embedding credentials in the project.

./build.sh
./build.sh --check
./build.sh --serve

The first environment synchronization may fetch locked dependencies. Once the dependency cache and source inputs exist, normal builds require neither FontLab nor network access. Explicit native refresh is a separate source-production operation; it captures inside FontLab before generation and enrichment.

Generated coverage records every identity and exact source hash. Class indexes retain each member occurrence; identical captured text is linked to one full declaration. This sharing does not assert native inheritance or object identity.

Before contributing, agree to the repository's FontLab contributor license agreement. Change source or enrichment inputs, regenerate, verify rendered references and cross-links, and include tests for changed behavior. Preserve source attribution and the Qt/PySide documentation licenses.

Include build source

The source-lock helper compares documented inputs with their recorded SHA256 hashes. A normal build refuses changed input bytes. Review producer changes before requesting a lock refresh.

Source-lock helper
# this_file: scripts/source_lock.py
"""Pin the exact API source bytes across checkout and installed-artifact builds."""

import json
from pathlib import Path


def input_hashes(inputs: list[dict]) -> dict[str, str]:
    """Reject duplicate input identities instead of silently dropping their bytes."""
    actual = {}
    for row in inputs:
        if row["source"] in actual:
            raise ValueError("Duplicate API source input: " + row["source"])
        actual[row["source"]] = row["sha256"]
    return actual


def verify_inputs(locked: dict[str, str], inputs: list[dict]) -> None:
    """Fail for missing, new or modified source; never silently refresh a lock."""
    actual = input_hashes(inputs)
    changed = sorted(
        name
        for name in locked.keys() | actual.keys()
        if locked.get(name) != actual.get(name)
    )
    if changed:
        raise ValueError(
            "API source lock differs: "
            + ", ".join(changed[:10])
            + "; use --update-source-lock after reviewing source changes."
        )


def apply_lock(path: Path, inputs: list[dict], *, update: bool) -> dict:
    """Write only when explicitly requested; ordinary builds verify the pin."""
    sources = input_hashes(inputs)
    if update:
        path.write_text(
            json.dumps(
                {
                    "schema_version": 1,
                    "sources": sources,
                },
                indent=2,
                sort_keys=True,
            )
            + "\n"
        )
    if not path.exists():
        raise FileNotFoundError("API source lock missing; use --update-source-lock.")
    lock = json.loads(path.read_text())
    verify_inputs(lock["sources"], inputs)
    return lock