andygrove opened a new pull request, #6021: URL: https://github.com/apache/datafusion-comet/pull/6021
## Which issue does this PR close? Closes #6020. ## Rationale for this change None of the mermaid diagrams on the published site render. They show as raw diagram source, for example on [memory_management](https://datafusion.apache.org/comet/contributor-guide/memory_management.html) and [ci](https://datafusion.apache.org/comet/contributor-guide/ci.html). The diagram sources are fine (both parse under mermaid 11.12.1) and so is the pinned CDN module (HTTP 200). The problem is where the renderer comes from. `sphinxcontrib-mermaid` defaults to `mermaid_output_format = 'raw'`, which draws the diagrams in the reader's browser and emits: ```js import mermaid from "https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.esm.min.mjs";; ``` The ASF serves `*.apache.org` with a `Content-Security-Policy` whose `script-src` allows only `'self'`, `data:`, `blob:` and a few apache.org / apachecon / scarf.sh hosts. `cdn.jsdelivr.net` is not among them, so the browser blocks the import and mermaid.js never loads. The same header is served on `airflow.apache.org` and `arrow.apache.org`, so this comes from ASF infrastructure, and `.asf.yaml` exposes no way to change it. Drawing the diagrams at build time sidesteps the policy entirely: the output is an SVG served from `'self'` and no script is involved. `apache/arrow` sets the same option for the same reason, and their diagrams render. ## What changes are included in this PR? - `docs/source/conf.py`: set `mermaid_output_format = 'svg'`, plus `mermaid_params = ['-b', 'transparent']` so a single image suits both the light and dark site themes (mmdc otherwise bakes in a white background). Diagrams stay authored as ` ```mermaid ` fences, so they continue to render on github.com. - `.github/workflows/docs.yaml`: install Node and `@mermaid-js/mermaid-cli`, which provides the `mmdc` binary the build now needs. - `docs/requirements.txt`: raise the `sphinxcontrib-mermaid` floor to 2.1. That is the first release that skips the client-side mermaid machinery when the output format is not `raw`. On older versions the diagrams still render correctly, but each page carrying one also gets a dead `cdn.jsdelivr.net` script tag. - `docs/README.md`: document `mmdc` as a docs build dependency, including that a build without it succeeds but quietly drops the diagrams. ## How are these changes tested? The docs site has no automated tests, so this was verified by building the affected pages locally in a virtualenv created from the updated `docs/requirements.txt` (resolving sphinxcontrib-mermaid 2.1.1, the same version CI installs), with `mermaid-cli` 11.17.0 on `PATH`: | page | `<object>` SVG embeds | `pre.mermaid` blocks | `cdn.jsdelivr.net` refs | | --- | --- | --- | --- | | `contributor-guide/memory_management.html` | 2 | 0 | 0 | | `contributor-guide/ci.html` | 1 | 0 | 0 | The build succeeds with 47 warnings, matching the pre-existing baseline, and all three generated SVGs carry `background-color: transparent`. Before this change the same pages contained unrendered `<pre class="mermaid">` blocks and a blocked jsdelivr module import. -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
