# Add PDF Export to Sphinx Docs

Yes. An agent configures Sphinx's LaTeX builder, adds a tox environment and a workflow that builds the PDF on release, checks the output page by page and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-pdf-export/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 documentation build before it adds a second output, because the PDF has to come from the same sources and settings as the HTML. In a project like pallets/click, `docs/` holds 37 Markdown files read through `myst_parser`; `docs/conf.py` loads `sphinx.ext.autodoc`, `sphinx.ext.extlinks`, `sphinx.ext.intersphinx`, `sphinx_tabs.tabs`, `sphinxcontrib.log_cabinet` and `pallets_sphinx_themes`, takes `release` and `version` from the installed package through `get_version`, sets `html_theme = "click"` and an SVG logo, and has no `latex_` setting at all. `docs/index.md` opens with an `{image}` directive for `_static/click-name.svg`, then runs `click:example` and `click:run` directives inside `{eval-rst}` blocks that execute the example while the docs build; four pages use `.. tabs::`, `docs/changes.md` includes `../CHANGES.md`, and `docs/contrib.md` is a table of remote badge images. `pyproject.toml` keeps a `docs` dependency group, `uv.lock` pins Sphinx 8.1.3 and myst-parser 4.0.1, and `[tool.tox.env.docs]` runs `sphinx-build -E -W -b dirhtml docs docs/_build/dirhtml`. `.readthedocs.yaml` builds only HTML, with `uv run --group docs`, and `.github/workflows/tests.yaml` ignores `docs/**` entirely.

Sphinx's own documentation sets the terms. The LaTeX builder writes `.tex` sources, and `sphinx-build -M latexpdf` runs them through `latexmk` in one step; on Ubuntu the packages that must be present are `texlive-latex-recommended`, `texlive-fonts-recommended`, `texlive-fonts-extra`, `tex-gyre`, `texlive-latex-extra` and `latexmk`, with the default `pdflatex` engine. The builder cannot place an SVG, and `sphinx.ext.imgconverter` converts images to a format the builder takes using ImageMagick, so the agent adds that extension and `imagemagick` to the package list; the Sphinx note that ImageMagick rasterises SVG goes into the pull request, with `sphinxcontrib-svg2pdfconverter` named as the vector alternative. In `docs/conf.py` the agent adds `latex_documents = [("index", "click.tex", "Click Documentation", "Pallets", "manual")]`, `latex_logo = "_static/click-logo.svg"`, `latex_show_urls = "footnote"` so printed links keep their targets, and a `latex_elements` dictionary with `papersize` and a `preamble` that loads nothing the theme does not need, since the `click` HTML theme has no bearing on the LaTeX output.

The build gets a home beside the HTML one: `[tool.tox.env.docs-pdf]` in `pyproject.toml`, using the same `docs` dependency group and running `sphinx-build -M latexpdf docs docs/_build -E`, without `-W`, because the LaTeX writer reports things the HTML build does not and the agent prefers a PDF with listed warnings to no PDF; the warnings it saw go into the pull request so a reviewer can decide whether to promote them to errors later. A `.github/workflows/docs-pdf.yaml` runs on a pushed tag and on `workflow_dispatch`, with `permissions: {}` and the same pinned `actions/checkout`, `astral-sh/setup-uv` and `actions/setup-python` steps as `tests.yaml`, installs the TeX Live packages and ImageMagick with `apt-get`, runs `uv run --locked --no-default-groups --group dev tox run -e docs-pdf`, uploads `docs/_build/latex/click.pdf` as a workflow artifact, and on a tag attaches it to the release with `gh release upload`, with `contents: write` granted to that job alone.

Before opening the pull request the agent builds the PDF in its sandbox the way the workflow would and reads it: it installs the packages, runs the tox environment, confirms the `click:run` examples rendered as code blocks, looks at the four pages that use `.. tabs::`, whose LaTeX output is not the tab widget, and describes how they came out, checks the badge table from `contrib.md` and the converted logo, and records the page count and the warnings the LaTeX writer printed. `docs/_build/` is already excluded from the source distribution, so the new output needs no packaging change.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a PDF build of this project's Sphinx documentation. Read docs/conf.py, docs/index.md, every page under docs/, pyproject.toml, uv.lock, .readthedocs.yaml and the workflows first. In docs/conf.py add latex_documents, latex_logo, latex_show_urls and a minimal latex_elements, and add sphinx.ext.imgconverter because the pages use SVG and remote badge images. Add a tox environment docs-pdf that runs sphinx-build -M latexpdf with the docs dependency group, without -W, and a workflow docs-pdf.yaml that runs on a pushed tag and on workflow_dispatch, installs the TeX Live packages Sphinx's documentation lists plus latexmk and ImageMagick, runs the tox environment through uv, uploads the PDF as an artifact and attaches it to the release on a tag, pinning the actions as the existing workflows do. Build the PDF in the sandbox, open it, record the page count and every warning, and report how the tabbed pages and the executed examples rendered. Do not change any documentation page. Open a pull request with the commands and 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` and `pyproject.toml` and adds `.github/workflows/docs-pdf.yaml`. Its description quotes the `sphinx-build -M latexpdf` output from the sandbox, the warnings the LaTeX writer printed with the page each came from, the page count of the resulting PDF, and the `apt-get` line the workflow uses so a reader can reproduce the build locally. No page under `docs/` changes, and the HTML build, `tox run -e docs`, still runs with `-W` exactly as before.

A reviewer checks the title and author in `latex_documents`, whether the PDF should also be built on every pull request rather than on tags only, which doubles a job that installs TeX Live, and whether the Read the Docs configuration should gain a `pdf` build so the hosted site offers the download too; the pull request shows the `.readthedocs.yaml` lines for that without adding them. After merging, the next tag produces the first attached PDF.

## Run it on every Sphinx project with HTML docs only

A team that maintains several libraries sends this body once per repository from its own server, each `POST /o/{org}/sessions` naming one repository in `resources` and carrying a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own `conf.py` and build: a project whose docs are reStructuredText needs no MyST handling, a project that already has `latex_documents` gets only the workflow, and a project with no tox gets the build command in the workflow directly.

The key's `webhook_url` reports each run the key starts with the pull request URL in `result`, so a script that sent the requests collects the pull requests without polling.

## Why run it on Rush?

A LaTeX build is the one documentation output nobody runs locally, and it fails on things the HTML build never sees: an SVG the builder cannot place, a directive whose LaTeX output differs from its HTML, a remote image that has to be fetched and converted. The agent installs TeX Live and ImageMagick in its own sandbox, builds the PDF, reads it page by page and keeps every command and warning in the run's record, so the pull request describes the PDF that exists rather than a configuration expected to produce one.

The additions follow the repository's own conventions: a tox environment beside the existing `docs` one, a workflow that pins the same action commits as `tests.yaml`, and the `docs` dependency group reused rather than a second list. Several projects with the same layout get several pull requests, each with its own warnings and page count.

## Frequently asked questions

### Why not build the PDF on Read the Docs instead?

You can, and the pull request shows the `.readthedocs.yaml` lines for a `pdf` job beside the existing HTML one. The workflow is there so the PDF is attached to the GitHub release and built from the tagged commit; the two are independent and either can be dropped.

### Why is -W left off the PDF build?

Because the LaTeX writer reports warnings the HTML build never raises, and a release workflow that fails on one of them produces no PDF at all. The pull request lists every warning the sandbox build printed; once they are fixed or accepted, `-W` can be added to the tox environment in one line.

### What happens to the SVG logo and the badge images?

`sphinx.ext.imgconverter` converts them with ImageMagick during the build, which rasterises SVG. For a vector logo, Sphinx's documentation names `sphinxcontrib-svg2pdfconverter`, and the pull request says where it would go; the remote badges are fetched during the build and converted the same way.

### Do the tabbed sections and executed examples work in the PDF?

The `click:run` directives execute during any Sphinx build, so the PDF carries the same output as the HTML. The `.. tabs::` sections are not rendered as a widget in LaTeX, and the pull request describes how each of the four pages came out so a reviewer can decide whether to restructure them.

### How big is the CI job?

The TeX Live packages are the bulk of it, which is why the workflow runs on tags and on demand rather than on every pull request. The pull request records how long the sandbox build took to install and to run, so a reviewer can judge whether to add it to pull requests too.

## More Sphinx jobs

- [Add Redirects for Moved Pages to Sphinx Docs](https://getrush.ai/run/add-redirects/sphinx/)
- [Add a Sitemap to a Sphinx Docs Site](https://getrush.ai/run/add-sitemap/sphinx/)
- [Add Social Cards to Sphinx Docs](https://getrush.ai/run/add-social-cards/sphinx/)

## The same job on other stacks

- [Add PDF Export to an mdBook Book](https://getrush.ai/run/add-pdf-export/mdbook/)
- [Add PDF Export to a MkDocs Site](https://getrush.ai/run/add-pdf-export/mkdocs/)

## More jobs like this: Hand off a long task

- [Add PDF Upload to a Streamlit File Q&A App](https://getrush.ai/run/add-pdf-support/streamlit/)

## 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/)
