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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Add PDF Export to an mdBook Book (mdBook)
- Add PDF Export to a MkDocs Site (MkDocs)
More jobs like this: Hand off a long task
- Add PDF Upload to a Streamlit File Q&A App (Streamlit)