All jobs

Add Open Graph Tags to Sphinx Docs

Yes. An agent adds sphinxext-opengraph to your Sphinx docs so every page carries og:title, og:description, og:url and an image, builds to check, 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 what the docs already put in <head> and how they are built, because the right values depend on the theme, the builder and the host. In a project laid out like psf/requests, docs/conf.py enables sphinx.ext.autodoc, intersphinx, todo and viewcode, uses the alabaster theme with github_user, github_repo and github_banner set, takes version and release from requests.__version__, serves docs/_static/custom.css and a requests-sidebar.png that docs/_templates/sidebar.html places as the logo, and sets no html_logo, no html_baseurl and nothing that writes an og: meta. .readthedocs.yaml builds with the dirhtml builder on Ubuntu 22.04 and Python 3.12, installs the package and docs/requirements.txt, which pins Sphinx==7.2.6 beside the test tools, and also produces PDF and EPUB. The root Makefile has a docs target that runs cd docs && make html, and .pre-commit-config.yaml excludes docs/ from its hooks.

Then it reads the extension. sphinxext-opengraph is one line in extensions, sphinxext.opengraph, and a handful of settings: ogp_site_url for the public address, which it reads from READTHEDOCS_CANONICAL_URL on Read the Docs so a local build and the hosted one agree; ogp_image for the picture a share card shows, resolved against the site URL when relative; ogp_site_name defaulting to project; ogp_description_length at 200 characters taken from the page; ogp_enable_meta_description on by default, which also adds a plain <meta name="description"> the docs lack today; ogp_type at website; and ogp_social_cards, which generates a PNG per page through matplotlib when the social_cards extra is installed, using html_logo as the picture unless image names another.

The agent writes the config for this site: sphinxext.opengraph in extensions, ogp_site_url set to the Read the Docs address with a note that the environment variable overrides it there, ogp_image pointing at _static/requests-sidebar.png, since that is the only logo the project has and html_logo is unset, ogp_site_name left to project, and ogp_custom_meta_tags carrying a twitter:card of summary so the card reads the same tags. It pins sphinxext-opengraph in docs/requirements.txt next to Sphinx 7.2.6 at a version that supports it, and leaves social cards off with a comment on how to turn them on, because they add matplotlib and a font to the Read the Docs build and the pull request should not change its duration without a decision.

To check the result the agent builds the docs twice in its sandbox with the same commands the hosts use: sphinx-build -b dirhtml docs docs/_build/dirhtml, since dirhtml turns user/quickstart.rst into user/quickstart/index.html and og:url must end in the directory form, and make html from the root target. It greps the built pages for og:title, og:url and og:description, reads the description the extension took from the quickstart page to see that it is the first paragraph and not a directive, and confirms the PDF and EPUB builders are untouched by an HTML-only extension.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add Open Graph meta tags to this project's Sphinx documentation. Read docs/conf.py, docs/requirements.txt, .readthedocs.yaml, docs/_templates/sidebar.html, docs/index.rst, docs/user/quickstart.rst, the root Makefile and docs/Makefile first. Add sphinxext.opengraph to extensions in docs/conf.py with ogp_site_url set to the Read the Docs address, ogp_image pointing at the sidebar logo in docs/_static, and a twitter:card meta through ogp_custom_meta_tags; leave social cards off with a comment on how to enable them. Pin sphinxext-opengraph in docs/requirements.txt at a version compatible with the pinned Sphinx. Build with sphinx-build -b dirhtml and with make html in your sandbox, grep the output for og:title, og:url and og:description on the index, quickstart and api pages, check the og:url values use the dirhtml directory form, and open a pull request with the head of one built page and the grep counts. Do not change the theme, the sidebar template or any .rst file.",
  "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 and docs/requirements.txt and nothing else. Its description pastes the <head> of the built quickstart page with the new og: and twitter:card metas, the og:url of three pages in the dirhtml form, the description text the extension chose for each, and the count of built pages carrying an og:title.

Read the Docs builds the pull request as it builds every other, installing the new pin from docs/requirements.txt, and the dirhtml output it serves gets the same tags the sandbox build showed. The PDF and EPUB formats in .readthedocs.yaml are unaffected.

Before merging, a reviewer checks the description chosen for the index page reads well on a card, decides whether to turn on social cards for a per-page image, and whether ogp_site_url should be the versioned address or the latest one.

Run it on every Sphinx project with bare share cards

A team that maintains several Sphinx projects sends this body once per repository from its own server: one POST /o/{org}/sessions each, with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. GET /o/{org}/github lists the repositories the Rush GitHub App installation can reach, so the script can pick the ones with a conf.py and no sphinxext.opengraph. Each run reads its own config: a project with html_logo set gets that as the image, one on the html builder gets .html page URLs, and one whose theme already writes og: tags gets no change and a note saying so.

A docs site that is rebuilt from a release event can start the same run from a handler on the reader's server after the tag is pushed, so the tags are checked on the version that was just published.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The tags are a few lines of config, and the values are only right when they match the builder, the host and the logo the project already has: an og:url with .html on a dirhtml site, an image path that resolves locally and 404s on Read the Docs, a description that starts with a badge. The agent reads the build configuration first, builds the docs in its own sandbox the way the hosts do, and reads the tags out of the HTML it produced.

The build output and the grep stay with the run and are pasted into the pull request, so the reviewer sees the card values rather than the config that should produce them. The same request runs for every documentation project a team maintains at once.

Frequently asked questions

Why not turn on social cards?

Social cards generate a PNG per page with matplotlib and a bundled font, which adds packages and time to the Read the Docs build. The pull request leaves them off with a commented ogp_social_cards block so a maintainer can turn them on in a follow-up; the sidebar logo is used as a static og:image in the meantime.

Where does the description come from?

From the page itself: the extension takes up to ogp_description_length characters of its text, 200 by default. The agent reads what that produced for the index and quickstart pages and pastes it into the description so a reviewer can see whether the first paragraph is the right summary.

Why set `ogp_site_url` when Read the Docs sets it?

Read the Docs exposes READTHEDOCS_CANONICAL_URL and the extension reads it, so the hosted build needs nothing. A local build has no such variable, and without a site URL the og:url and the image path are incomplete, so the config sets the address as the fallback.

Does this change the PDF or EPUB output?

No. The extension adds meta elements to HTML pages only; the formats list in .readthedocs.yaml still builds PDF and EPUB from the same sources, and the agent's sandbox build confirms those builders run unchanged.

More Sphinx jobs

The same job on other stacks

Keep reading