fix(doc): SVG images not rendering

[junrushao]

It turns out that SVG images below [link]:

• https://raw.githubusercontent.com/tlc-pack/web-data/refs/heads/main/images/tvm-ffi/stable-c-abi-layout-any.svg
• https://raw.githubusercontent.com/tlc-pack/web-data/refs/heads/main/images/tvm-ffi/stable-c-abi-layout-func.svg
  are not rendering properly.

Not entirely sure why. This commit tries out some fixes chatgpt suggests...

[gemini-code-assist]

Summary of Changes

Hello @junrushao, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses a critical issue where SVG images embedded in the documentation were failing to render correctly. The changes focus on modifying the image source URLs to ensure their proper display, specifically by adjusting the path structure and adding a sanitization parameter to the raw GitHub content links, based on suggestions to resolve common SVG rendering problems.

Highlights

• Documentation Fix: Updated SVG image URLs in docs/get_started/stable_c_abi.rst to resolve rendering issues. The fix involved removing refs/heads/ from the image paths and appending ?sanitize=true to the URLs.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request correctly fixes an issue where SVG images were not rendering in the documentation by appending ?sanitize=true to the image URLs. This works because it forces GitHub to serve the images with the correct image/svg+xml content type, which is required for browsers to render them. While this change is effective, I've added a comment suggesting a more robust long-term solution: including the images directly within this repository. This would make the documentation self-contained and remove the dependency on raw.githubusercontent.com.

[gemini-code-assist]

While adding ?sanitize=true fixes the rendering, a more robust approach is to store the images within this repository, for example in a docs/_static/images/ directory. This makes the documentation self-contained, removes the dependency on raw.githubusercontent.com, and avoids potential issues with GitHub's file serving policies in the future. You could then reference the image with a relative path, for example: .. figure:: /_static/images/tvm-ffi/stable-c-abi-layout-any.svg.

[junrushao]

turns out it still doesn't work

[junrushao]

Here's what chatgpt says:

This happens because the published site is trying to load your SVG from a third‑party origin (raw.githubusercontent.com). That works on your machine (no strict security headers), but on tvm.apache.org the page is served with a Content Security Policy (CSP) that disallows embedding external resources. The source of the page shows the figure still points at the GitHub raw URL, so the browser must fetch it cross‑origin; ASF’s website policy (effective Mar 1, 2025) explicitly restricts embedding third‑party content, which is why it fails on the live site. ([tvm.apache.org]1)

Best fix (recommended)

Serve the image from the docs site itself (no hotlinking).

1. Put the SVG under your Sphinx source tree, e.g. docs/_static/img/tvm-ffi/stable-c-abi-layout-any.svg.
2. Change the directive to a local path (relative to the .rst file):

.. figure:: ../_static/img/tvm-ffi/stable-c-abi-layout-any.svg
   :alt: Layout of the 128-bit Any tagged union
   :name: fig:layout-any

Sphinx will copy local images into the build output and rewrite the <img src> to a same‑origin URL, so CSP is satisfied. ([JetBrains]2)

Tip: You don’t have to use _static; any folder under the Sphinx source works. Sphinx will place the files into _images in the HTML build.

If you need a single source of truth for images (but still comply with CSP)

Option A — Git submodule or sync step

• Add the shared image repo as a submodule and reference the files locally:

git submodule add https://github.com/tlc-pack/web-data docs/_static/web-data

Then in your .rst:

.. figure:: ../_static/web-data/images/tvm-ffi/stable-c-abi-layout-any.svg
   :alt: Layout of the 128-bit Any tagged union
   :name: fig:layout-any

Or add a pre‑build step (in CI) that curl/wgets the assets into your docs tree before sphinx-build. End result is still a same‑origin image.

Option B — Have Sphinx download remote images at build time

If you really want to keep URLs in the docs, use an extension that downloads remote images during the build and serves them locally.

• Install and enable [sphinxcontrib-images](https://pypi.org/project/sphinxcontrib-images/):

  # conf.py
  extensions = ['sphinxcontrib.images']
  images_config = {
      'download': True,        # ensure remote images are fetched
      'cache_path': '_images', # where to keep downloaded assets
  }

  Then use its thumbnail directive (or override the default image handling) so the URL is fetched and stored into your build’s _images/, avoiding CSP issues. Note: thumbnails aren’t numbered like figures; if you rely on :numref:, stick with local files + figure. ([sphinxcontrib-images.readthedocs.io]3)

What not to do (or why the current approach breaks)

• Keeping .. figure:: https://raw.githubusercontent.com/... relies on cross‑origin loads. ASF’s CSP forbids embedding third‑party content on project sites, so this will continue to fail on tvm.apache.org. ([infra.apache.org]4)
• The ?sanitize=true on GitHub SVGs doesn’t help with CSP; it only affects how GitHub serves the SVG. The CSP check happens in the browser on tvm.apache.org.

Bonus: if you also build PDF

LaTeX can’t embed SVG directly. If you keep SVGs, add one of these to conf.py so PDF builds keep working:

extensions += ['sphinx.ext.imgconverter']  # uses ImageMagick
# or
extensions += ['sphinxcontrib.rsvgconverter']  # converts SVG -> PDF

([sphinx-doc.org]5)

---

Bottom line: Move (or vend) the image into the docs repository and reference it locally. That’s the simplest, CSP‑compliant, and most robust fix for tvm.apache.org.