All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

Keep reading