ColtenOuO opened a new pull request, #72006: URL: https://github.com/apache/airflow/pull/72006
### Sumarry Render the database ERD reference pages (core, FAB, Edge3) as a Mermaid `erDiagram` instead of an SVG image, so table and column names are indexed by search engines and in-page search instead of being locked inside a picture. closes: #36842 ### Before / after **Before** — the current production docs (`apache-airflow` 3.4.0) embed the ERD as a flat SVG image. On a schema this size (57 core tables) the image is dense and hard to read even at full screen, and none of the table/column text is selectable or searchable: <img width="1859" height="731" alt="image" src="https://github.com/user-attachments/assets/ce7706ee-07c3-406f-9767-a5068abfb9ff"; /> **After** — same page, rendered as a Mermaid diagram from this branch. Every table/column name is now real page text: here the browser's in-page search (`Cmd+F`) for "INTEGER" finds 50 matches on the FAB provider's ERD page: <img width="1774" height="932" alt="image" src="https://github.com/user-attachments/assets/79643b70-abc1-446c-946c-39c24b59e259"; /> Same on the Edge3 provider's ERD page (a much smaller schema, so also easier to read as a bonus) — 7 matches for "INTEGER": <img width="1272" height="828" alt="image" src="https://github.com/user-attachments/assets/c81b5db9-595c-4a72-9e28-df250f1db0a4"; /> ### What changed - `generate_erd` (the Sphinx extension that (re)builds the diagram from the live SQLAlchemy models on every doc build) now writes Mermaid ER-diagram markup (`.mmd`) instead of an SVG. - The three `database-erd-ref.rst` pages (`airflow-core`, `providers/fab`, `providers/edge3`) use the `.. mermaid::` directive (already available via `sphinxcontrib-mermaid`, already used elsewhere in the docs) instead of `.. image::`. - Dropped the graphviz/`dot` availability check and its SVG placeholder — Mermaid markup is emitted directly by `eralchemy` without shelling out to graphviz, so that whole fallback path no longer applies. - Updated `.gitignore` and `contributing-docs/14_metadata_database_updates.rst` for the new generated filename. ### Why this wasn't done sooner An earlier attempt (#42323) stalled because it tried to introduce a new tool (`paracelsus`) and wasn't sure whether generating from live models vs. the post-migration database would let the diagram drift out of sync with the models. Both concerns are now moot: `generate_erd` already regenerates from the live SQLAlchemy `MetaData` on every doc build (introduced after that PR), and the `eralchemy` version already pinned in `devel-common` (`eralchemy==1.7.0`) can emit Mermaid ER-diagram markup directly — no new dependency needed. Note: `eralchemy`'s own `render_er(..., mode="mermaid_er")` wraps its output in an HTML comment plus a `mermaid.ink`-hosted image link (meant for GitHub-flavored markdown READMEs), which isn't right for a Sphinx `.. mermaid::` directive and would reintroduce an external-image dependency. This PR calls eralchemy's lower-level `all_to_intermediary`/`filter_resources`/`_intermediary_to_mermaid_er` functions directly to get the raw `erDiagram ...` markup instead. ### Testing - Ran the extension against the real core/FAB/Edge3 SQLAlchemy models and confirmed clean Mermaid markup is produced (57 core tables). - Built all three affected packages with `breeze build-docs --package-filter apache-airflow --package-filter apache-airflow-providers-fab --package-filter apache-airflow-providers-edge3` — build and spellcheck succeeded for all three, and the rendered HTML contains the ERD text (e.g. `dag_run`) directly in the page rather than in an image, with no `mermaid.ink` reference. - `prek run --stage pre-commit` passes on the changed files, including `mypy` for `devel-common`. --- ##### Was generative AI tooling used to co-author this PR? - [X] Yes — Claude Code (Sonnet 5) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
