# Add Social Cards to Sphinx Docs

Yes. An agent adds sphinxext-opengraph to a Sphinx site with Furo, generates a preview card per page, keeps the strict build green and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-social-cards/sphinx/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the docs build before it adds an extension to it. In a project like python-attrs/attrs, `docs/conf.py` lists eight extensions, `myst_parser`, `sphinx.ext.napoleon`, `autodoc`, `doctest`, `intersphinx`, `todo`, `notfound.extension` and `sphinxcontrib.towncrier`, sets `html_theme = "furo"` with `light_logo` and `dark_logo` pointing at `attrs_logo.svg` and `attrs_logo_white.svg` in `docs/_static`, reads `html_baseurl` from the `READTHEDOCS_CANONICAL_URL` environment variable, and sets `html_static_path = ["_static"]`. That directory already holds a hand-made `social card.png` next to its `.afdesign` source, `attrs_logo.png` and `docset-icon.png`, but nothing in `conf.py` emits an `og:image` tag, so a link to any page previews with no image. The docs dependencies are the `docs` group in `pyproject.toml`: `cogapp`, `furo`, `myst-parser`, `sphinx`, `sphinx-notfound-page`, `sphinxcontrib-towncrier` and `towncrier`, locked in `uv.lock`. `tox.ini` builds with `sphinx-build -n -T -W -b html docs docs/_build/html` in the `docs-build` environment, so every warning fails the build, and `.readthedocs.yaml` runs that same tox environment through `uv`. CI's docs job runs `docs-doctests` and `changelog`, not the HTML build.

sphinxext-opengraph, at 0.13.0 the current release, adds the tags. Its docs name the extension `sphinxext.opengraph`, make `ogp_site_url` the one setting that matters, with Read the Docs detected from `READTHEDOCS_CANONICAL_URL` on its own, and default `ogp_site_name` to the project name, `ogp_description_length` to 200, `ogp_type` to `website` and `ogp_enable_meta_description` to true. Installing the `social_cards` extra brings matplotlib, and `ogp_social_cards` then renders one PNG per page with the site name, the page title and description, a border line and an image in the corner, which falls back to the HTML logo when `image` is unset; the docs say the image must be a PNG or JPEG, not an SVG, which rules out the two logos `conf.py` uses for Furo.

The agent adds `sphinxext-opengraph[social_cards]` to the `docs` group in `pyproject.toml` and runs `uv lock` so `uv.lock` carries it and matplotlib, since tox uses the lock to build its environments. In `conf.py` it appends `sphinxext.opengraph` to `extensions`, sets `ogp_site_url` to the documentation URL from `[project.urls]` as the value for local builds, sets `ogp_social_cards` with `enable` true, `image` pointing at `_static/attrs_logo.png`, the PNG logo already in the tree, and a `line_color` taken from the theme's accent, and sets `ogp_image_alt` to the project's description from `pyproject.toml`. The card's title comes from each page's own title, so the API reference, the changelog and the examples page each get their own preview. The hand-made `social card.png` stays where it is, and the pull request names the field-list override the extension reads for a page that should use it instead.

Then the agent builds the way Read the Docs does: `uv run --only-group tox tox run -e docs-build`, which must finish with no warning under `-W`. It reads `docs/_build/html/index.html` and `docs/_build/html/api.html` for the `og:title`, `og:description`, `og:url` and `og:image` tags, confirms the image paths point at PNG files written under `_images/social_previews/`, and opens two of the PNGs in its own browser to see the title and logo render. It also runs `docs-doctests`, the environment CI runs, to show nothing else moved. A line in `.github/CONTRIBUTING.md`, whose docs section already names the `docs-build` and `docs-doctests` tox environments, mentions the extension.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add Open Graph tags and generated social cards to this project's Sphinx documentation. Read docs/conf.py, pyproject.toml, uv.lock, tox.ini, .readthedocs.yaml, .github/workflows/ci.yml, the docs directory and docs/_static first. Add sphinxext-opengraph with the social_cards extra to the docs dependency group and update the lock file. In conf.py enable sphinxext.opengraph, set ogp_site_url to the documentation URL for local builds, set ogp_image_alt to the project description, and configure ogp_social_cards with a PNG logo from _static as the card image and a line colour matching the theme. Build with the tox docs-build environment, which treats warnings as errors, and confirm the og tags and the generated card PNGs on the index and API pages. Run the docs doctests too. Add a line to the docs section of .github/CONTRIBUTING.md. Open a pull request with the commands and their output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `docs/conf.py`, `pyproject.toml`, `uv.lock` and `.github/CONTRIBUTING.md`. Its description quotes the `tox run -e docs-build` output ending without warnings, the `docs-doctests` result, the four `og:` tags from `index.html` and `api.html`, the list of PNGs written under `_images/social_previews/`, and two of the cards as images. No page source changes.

A reviewer checks the line colour, whether the landing page should use the hand-made `social card.png` through a page override instead of a generated card, and whether the docs group should carry matplotlib or the cards should be off and only the tags kept, which is `enable` set to false. After merging, the next Read the Docs build publishes the tags and the cards with no change to the Read the Docs settings.

## Run it on every Linear issue labelled docs

An automation in the Project that holds the repository takes a `linear` trigger on `linear.issue.labeled` with the label `docs`. Its runs are read-only, so the saved prompt asks for a plan: the run reads `conf.py` and the dependency groups, says which extension and settings it would add and what the strict build would need, and posts that as a comment on the issue. A handler on the team's server then starts the run that writes the pull request, sending this body with the issue's URL in `resources` and a `request_id` that is a UUID v5 of the issue id, so a retried start returns the run already started.

A team with several Sphinx projects sends one request per repository, each with its own `resources` entry.

## Why run it on Rush?

A `-W` build is unforgiving, and matplotlib rendering fonts inside a Sphinx run is the kind of step that works on one machine and fails on another, so the proof is a clean build with the project's own tox environment. The agent runs it in its own sandbox, reads the generated HTML and PNGs, opens the cards in a browser and keeps every command and its output in the run's record, so the pull request shows the tags and the images rather than describing them.

The change fits the project as it is: the `docs` dependency group and `uv.lock` that tox reads, the Read the Docs environment variable the extension already understands, and the PNG logo the tree already has. Ten projects with ten themes get ten pull requests, each with that project's own card image and colour.

## Frequently asked questions

### Why not use the social card that is already in _static?

It can be used, and the pull request names the per-page override for it. The generated cards carry each page's own title, so a link to the changelog or the API reference previews as that page rather than as the project in general, which the one hand-made image cannot do.

### Will this break the strict docs build?

The build in `tox.ini` runs with `-W` and `-n`, and the agent's run finishes it without a warning before opening the pull request. The site URL is set in `conf.py` for local builds, and Read the Docs supplies its own through `READTHEDOCS_CANONICAL_URL`, which the extension reads on its own.

### Does this add a heavy dependency?

The `social_cards` extra pulls in matplotlib, which the extension uses to draw the PNGs, and it lands in the `docs` group only, not in the package or the test groups. Setting `enable` to false in `ogp_social_cards` keeps the Open Graph tags and drops the drawing and the dependency.

### Can I change the image or text for one page?

Yes. The extension reads field lists at the very start of a page, such as `:og:image:` with an absolute URL or `:og:description:`, and `:ogp_disable:` turns the tags off for a page. The pull request shows the syntax for a MyST page and for a reStructuredText page.

## More Sphinx jobs

- [Add a Typo Check to a Sphinx Documentation Site](https://getrush.ai/run/add-typo-check/sphinx/)
- [Fix "The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0"](https://getrush.ai/run/fix-sphinxcontrib-applehelp-version-error/sphinx/)
- [Add a Copy Button to Sphinx Code Blocks](https://getrush.ai/run/add-copy-button/sphinx/)

## The same job on other stacks

- [Add Social Cards to a VitePress Blog](https://getrush.ai/run/add-social-cards/vitepress/)
- [Add Social Cards to an Eleventy Blog](https://getrush.ai/run/add-social-cards/eleventy/)
- [Add Social Card Images to a Gatsby Blog](https://getrush.ai/run/add-social-cards/gatsby/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
