perf: eliminate O(docs) disk reads in check_all_figures_have_license

[lkdmc]

Summary

check_all_figures_have_license previously called env.get_doctree(docname) for every document in env.found_docs, which reads and unpickles each doctree file from disk on every build — including incremental builds where only a few documents changed. For large projects this produced significant unnecessary I/O proportional to the total number of documents.

Changes

MetadataFigure.run() — record each processed figure's image_uri and license value into env.metadata_figure_license_index[docname] as a plain dict. This is pure in-memory bookkeeping with no extra I/O.

check_all_figures_have_license() — iterate the index directly; fall back to env.get_doctree() only for documents not present in the index (unchanged docs from a previous incremental build, or figures emitted by third-party extensions).

clear_page_defaults() — also clear env.metadata_figure_license_index entries for documents that are about to be rebuilt, so stale entries from a previous run do not survive into the new build.

merge_figure_license_index() — new env-merge-info event handler that merges the index from each parallel read worker back into the main env, keeping parallel_read_safe = True fully functional.

Complexity

Scenario	Before	After
Full build (N docs)	O(N) disk reads	O(0) disk reads (index used)
Incremental build (k changed docs)	O(N) disk reads	O(N-k) disk reads (only unchanged docs fall back)

In the common incremental case where most docs are unchanged, the number of disk reads drops from O(N) to O(N-k), approaching zero for small changesets.

Test plan

• Enable summaries: true in metadata_figure_settings.license and run a full build; confirm missing/unrecognized license warnings still appear correctly.
• Run an incremental build after changing one document; confirm the summary still covers all documents, not just the changed one.
• Run a parallel build (sphinx-build -j auto) and confirm the summary is complete (index merge working).
• Confirm that figures produced by non-MetadataFigure directives (standard .. figure:: not overridden) still appear in the summary via the doctree fallback.

https://claude.ai/code/session_01ApsmWPWsKBesMV1rq2VenA