Proposal: emit a machine-readable execution_status.json for lecture build/execution status

[mmcky]

Proposal

Have each QuantEcon lecture build emit a machine-readable execution_status.json as a build artifact, alongside the existing human-readable status.html, so downstream tooling can consume build/execution status as structured data instead of scraping HTML.

Background

Every lecture site publishes an execution-statistics page (e.g. python.quantecon.org/status.html) with columns: Document · Modified · Method · Run Time (s) · Status (✅/❌).

The Operations Manual aggregates these into a global view (manual.quantecon.org/stats/lectures.html), but it does so by fetching and scraping each site's status.html live, client-side. There is no structured/machine-readable status source today — the data only exists as rendered HTML.

Problem

Scraping rendered HTML is fragile (any theme/markup change can break consumers) and limits what tooling can do:

• The global dashboard has to parse HTML per site on every page load.
• The weekly report (QuantEcon/action-weekly-report) can currently only link to the live dashboard, not embed period-relevant build health. See Weekly Report - Week Ending May 30, 2026 #313 and the "future option" note in QuantEcon/action-weekly-report#11.
• Any future alerting/monitoring (e.g. "which lectures are failing or slowest this week?") has nowhere structured to read from.

Proposed solution

The lecture build (MyST-NB / Jupyter Book) already has all of this data structured internally — it's the same source that renders status.html. We just don't expose it. The proposal is to also write it as JSON, e.g. published at a stable path such as /_static/execution_status.json (or the site root).

Sketch schema

{
  "schema_version": 1,
  "project": "lecture-python-intro",
  "built_at": "2026-05-29T04:41:00Z",
  "commit": "abc1234",
  "python_version": "3.13.9",
  "totals": { "documents": 72, "passing": 71, "failing": 1 },
  "documents": [
    {
      "name": "ar1_bayes",
      "modified": "2026-05-11T04:41:00Z",
      "method": "cache",        // cache | force | off
      "runtime_seconds": 257.35,
      "status": "ok"            // ok | error
    }
    // ...
  ]
}

(Field names/shape are a starting point — happy to iterate.)

Who benefits

• Operations Manual dashboard — parse a small JSON per site instead of scraping HTML; more robust and faster.
• Weekly report (action-weekly-report) — embed period build health (newly-failing lectures, slowest-executing, totals) directly, instead of only linking the live dashboard.
• Monitoring/alerting — a stable contract to build on (e.g. notify when a lecture flips to ❌).

Suggested adoption path

1. Emit execution_status.json in one pilot project (e.g. lecture-python-intro) from the existing status-page build step.
2. Roll it across lecture projects via the shared build workflow / quantecon-book-theme.
3. Migrate the manual dashboard to consume JSON (falling back to HTML scraping for not-yet-migrated sites).
4. Wire action-weekly-report to fetch + embed it.

References

• Global dashboard: https://manual.quantecon.org/stats/lectures.html
• Example status page: https://python.quantecon.org/status.html
• Weekly highlights improvements: Weekly Report - Week Ending May 30, 2026 #313
• Status-footer link + "future option" note: QuantEcon/action-weekly-report#11

Filed from the weekly-highlights work in #313 — the "can we report a global lecture status?" question. Linking the live dashboard is shipping now; this issue tracks the upstream change that would let us embed structured status instead.