Unreleased changes

Changes that have landed on the main branch but are not yet part of a tagged release. These entries are assembled into the Changelog when the next release is published.

[UNRELEASED DRAFT]

  • Add an “Understanding the result” documentation page that defines each LiteralizeResult field, explains when preamble and body_preamble are populated and that they must precede code to compile, and shows how wrap_in_file=True assembles those fields into output that compiles for you.

  • Document the variable_form argument with a “Binding the result to a variable” section that contrasts NewVariable, ExistingVariable, and BothVariableForms and shows the output each produces.

  • Group the documentation index into captioned “Guides”, “Reference”, and “Project / Development” sections, and correct the contributing guide to reference prek hooks and the uv run --extra dev pytest test command.

  • Move the language-definition (extension) API reference out of the consumer-facing API reference page and into the Languages guide, co-locating the Language protocol, the LanguageCls class, the *FormatConfig building blocks, and fixed_open with the narrative “Custom language implementations” how-to that already explains them.

  • Add a public LiteralizeResult.sections accessor (a tuple of the new FileSection dataclass) that exposes the file regions of a multi-section language’s wrap_in_file=False output, so a caller can compose each region into its own program template instead of parsing a language-internal marker. COBOL under json_type=CJSON is the first such language, surfacing its WORKING-STORAGE and PROCEDURE regions (named by the Cobol.CJSON_WORKING_STORAGE_SECTION / Cobol.CJSON_PROCEDURE_SECTION constants); its CI round-trip helper now composes those regions directly rather than splicing into a wrapped program.

  • Fold the resolution guidance for each exception into its class description (a “To resolve, …” sentence) and render the remaining stages of the “Common errors” documentation page with autoexception directives instead of hand-maintained Cause / How-to-resolve tables, so each exception’s meaning and recommended fix are single-sourced from literalizer.exceptions and can no longer drift between the page and the API reference.

  • Generate the per-language heterogeneous-strategy support matrix in the documentation from the language registry at build time (rendered with the sphinx-jinja extension), so it can no longer drift from the heterogeneous_strategies enum on each language class. This also corrects the previously stale matrix, which omitted several languages that now expose RECORD.