Embed a diagram in Sphinx: image directives take a URL, raw html takes the iframe

Point .. image:: at an https URL and Sphinx emits an img tag referencing it verbatim; the build never downloads the file into _images the way it copies local ones. Readers fetch the URL at view time, which is the live property: an endpoint that re-renders when the diagram changes keeps every built version of your docs current, five minute cache lifetime included.

Sphinx flags each such reference with a build warning, 'nonlocal image URI found', a deliberate nudge that your docs now depend on an external host. When that dependency is the point, silence just that warning with suppress_warnings in conf.py rather than turning warnings off globally, especially if CI builds with warnings-as-errors.

.. figure:: https://datadef.io/api/embed/my-platform-a1b2c3d4
   :alt: Platform architecture
   :width: 100%

   Current platform architecture. Rendered from the live diagram,
   so this figure follows the source without a docs rebuild.

.. In conf.py, silence the expected warning:
.. suppress_warnings = ["image.nonlocal_uri"]

The figure directive wraps the same image in a captioned, styleable container, and the caption is worth having on architecture diagrams: one sentence naming what the view shows and when it was last verified against the system spares readers the guess. Options like :width: and :align: apply to both directives.

For sharper output on wide layouts, the endpoint takes render parameters, format png or jpeg, width 600 to 4000, height 400 to 4000, scale 1 to 3, appended to the URL as a query string.

reStructuredText has no iframe construct, but the raw directive passes a block of HTML into the output for the html builder only, which is exactly the escape hatch an interactive embed needs: .. raw:: html followed by an indented iframe pointing at the embed page gives readers pan and zoom inside the docs. Other builders, LaTeX and PDF among them, skip raw html blocks silently, so pair the iframe with a figure fallback if your docs also ship as PDF.

The framed page must allow embedding; the Datadef embed page does, chrome-less with a small attribution link.

Projects using MyST-Parser get the same behaviors in markdown. Standard image syntax works inline, and the MyST figure directive in a colon or backtick fence takes the external URL plus alt, width, and a caption line, mirroring the reST figure. The nonlocal URI pass-through and its warning behave identically, since MyST feeds the same Sphinx image pipeline.

Raw HTML in MyST is off by default; rather than enabling it broadly, keep iframes in an eval-rst block with raw html, or accept the image form, which needs nothing special.

A Sphinx site often builds in CI on every merge, which is the natural place for the other half of the loop: the Datadef MCP server (registry name io.datadef/mcp) lets an agent with repository access update the diagram from what it reads in the code, in the same pipeline that builds the docs or on request during review. Datadef does not watch repositories; regeneration runs when an agent call or CI command asks. The agent runs on a key that a paid plan provides. Wire it next to your existing docs checks in CI.

Limits: the embed URLs exist only while the project is shared public, and 404 when it goes private. Datadef syncs diagrams, not prose; docstrings, autodoc output, and written guides remain your review process's responsibility.

• Embed diagrams in Markdown
• Embed diagrams in MkDocs
• Keep SDK docs in sync
• Docs checks in CI