Coverage Generation¶

This page is maintainer-facing. The public coverage and example pages are reference docs, but their tables are generated from plugin metadata, example metadata, and validation tests. Do not hand-edit generated sections between the AUTOGENERATED markers.

Keep user-facing text outside generated markers stable and explanatory. Put generator commands, artifact handling, pinned refs, and release-local checklists in maintainer docs, issues, or pull-request descriptions.

Generated Pages¶

Public page	Generator	Notes
`docs/user_guide/supported_components.md`	`poetry run python scripts/generate_readme.py`	Runs `scripts/generate_tests.py`, collects a pytest JSON report, then refreshes the generated component table.
`docs/user_guide/examples.md`	`poetry run python scripts/generate_readme.py`	Uses the same metadata/test-result pass as `supported_components.md`; Netron links come from testcase context and name.
`docs/user_guide/onnx_operator_coverage.md`	`poetry run python scripts/generate_onnx_operator_coverage.py`	Supports `--check`. Starts from the ONNX operator index and plugin `onnx` metadata.
`docs/user_guide/jax_lax_coverage.md`	`poetry run python scripts/generate_lax_operator_coverage.py`	Supports `--check`; also writes a local `work_notes_coverage3.md` review file.
`docs/user_guide/jax_numpy_coverage.md`	`poetry run python scripts/generate_jnp_operator_coverage.py`	Supports `--check`; also writes a local `work_notes_coverage_jnp.md` review file.
`docs/user_guide/flax_api_coverage.md`	`poetry run python scripts/generate_flax_api_coverage.py`	Supports `--check`; also writes a local `work_notes_coverage_flax.md` review file.
`docs/user_guide/equinox_nn_coverage.md`	`poetry run python scripts/generate_eqx_nn_coverage.py`	Supports `--check`; also writes a local `work_notes_coverage_eqx_nn.md` review file.

The work_notes_* outputs are maintainer review aids. Do not treat them as public documentation unless a specific review deliberately promotes their content into a stable docs page.

Update Workflow¶

Change plugin metadata, example metadata, lowerings, or tests.
Run the focused pytest target for the affected plugin or example.
Regenerate only the affected coverage/reference page.
Run the coverage-doc policy tests:

poetry run pytest -q \
  tests/extra_tests/framework/test_coverage_docs.py \
  tests/extra_tests/framework/test_coverage_generators.py

Run poetry run mkdocs build --strict before requesting review.

When checking freshness without rewriting files, use the generators that support --check:

poetry run python scripts/generate_onnx_operator_coverage.py --check
poetry run python scripts/generate_lax_operator_coverage.py --check
poetry run python scripts/generate_jnp_operator_coverage.py --check
poetry run python scripts/generate_flax_api_coverage.py --check
poetry run python scripts/generate_eqx_nn_coverage.py --check

scripts/generate_readme.py does not expose a --check mode. Review its diff after it refreshes supported_components.md and examples.md.

Stacktrace Fixtures¶

When stacktrace metadata keys or payload semantics change, refresh affected expect_graph snippets with stacktrace metadata enabled so structural expectations stay aligned with exported graph metadata:

JAX2ONNX_ENABLE_STACKTRACE_METADATA=1 \
  poetry run python scripts/emit_expect_graph.py <testcase>

Keep fixture updates focused on meaningful graph structure; stacktrace metadata is diagnostic context, not a reason to broaden an unrelated expectation.

ONNX Function Fixtures¶

The @onnx_function user feature is covered by converter regressions and generated examples. When function naming, reuse, namespacing, or call-time parameter behavior changes:

poetry run pytest -q \
  tests/extra_tests/converter/test_onnx_function_unique.py \
  tests/extra_tests/converter/test_onnx_function_call_params.py \
  tests/extra_tests/converter/test_onnx_function_deterministic_param.py \
  tests/examples/test_onnx_functions.py

Regenerate generated tests with poetry run python scripts/generate_tests.py. If the public component/example tables need updated status or links, follow with poetry run python scripts/generate_readme.py.

Keep post_check_onnx_graph expectations focused on meaningful structural checks. For imported function bodies, use search_functions=True and graph selectors such as "custom:MyFunction" or "fn:custom:MyFunction".