What the agent does
The agent reads how the docs are built before it adds a date, because the date has to survive a strict build in two places. In a project like pallets/click, docs/conf.py lists sphinx.ext.autodoc, sphinx.ext.intersphinx, sphinx_tabs.tabs, sphinxcontrib.log_cabinet, pallets_sphinx_themes and myst_parser, sets html_theme = "click", html_show_sourcelink = False and a versioned html_title, and sets no html_last_updated_fmt. pyproject.toml keeps the docs tools in a docs dependency group that uv.lock resolves, and its [tool.tox.env.docs] runs sphinx-build -E -W -b dirhtml docs docs/_build/dirhtml. .readthedocs.yaml says in its own comment that it specifies no sphinx key so it controls every step: an install job adds uv through asdf and the build.html job runs uv run --group docs sphinx-build -W -b dirhtml docs $READTHEDOCS_OUTPUT/html. The GitHub workflows never build the docs; tests.yaml ignores docs/** and pre-commit.yaml runs the hooks in .pre-commit-config.yaml, among them uv-lock, so a dependency added without relocking fails there.
Sphinx's own html_last_updated_fmt prints a footer line, but with the build time on every page, which says nothing about the page. The agent adds sphinx_last_updated_by_git to extensions and sphinx-last-updated-by-git to the docs group, then runs uv lock so the lock file and the pre-commit hook agree. The extension sets each page's date from the author date of the last commit that touched its source or any file it depends on, which matters for this project: docs/changes.md includes CHANGES.md from the repository root, so its date follows the changelog's last commit and not the stub page's. The agent sets html_last_updated_fmt = "%Y-%m-%d", which the theme shows because the click theme inherits pocoo, and pocoo/layout.html extends Sphinx's basic/layout.html whose footer prints the line whenever last_updated is set; with git_last_updated_timezone left at the default the day is the committer's local day, and the pull request names the setting for a team that wants UTC.
The shallow clone is the trap, and the agent walks into it on purpose. In a git clone --depth 1 of the project, which is what a hosted builder makes unless told otherwise, the extension cannot find the commit for any page and emits WARNING: Git clone too shallow [git.too_shallow] once per document, and the -W build the project insists on turns those into a failed build. The extension's documentation gives the fix for each host: a post_checkout job that runs git fetch --unshallow || true on Read the Docs, fetch-depth: 0 on actions/checkout. So the agent adds the post_checkout job to .readthedocs.yaml, beside the install job that is already there, and leaves suppress_warnings alone, because hiding the warning would print no date rather than the right one.
It proves both sides. In the shallow clone the strict build fails with one warning per page, and the agent keeps that output for the pull request as the reason the post_checkout job exists; after git fetch --unshallow the same command finishes clean, and the agent reads the footer of quickstart/index.html, index.html and changes/index.html from the dirhtml output to confirm three different dates, the last one matching git log -1 -- CHANGES.md. It also runs tox -e docs, since that is the command contributors use, and opens one page in its own browser to see where the theme puts the line.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a per-page last updated date to this project's Sphinx documentation using sphinx-last-updated-by-git. Read docs/conf.py, pyproject.toml (the docs dependency group and the tox docs environment), uv.lock, .readthedocs.yaml, .pre-commit-config.yaml and the workflows under .github/workflows first, and check whether the theme's layout extends Sphinx's basic layout so the footer shows last_updated. Add the extension to conf.py with html_last_updated_fmt set to an ISO date, add the package to the docs dependency group and run uv lock. Reproduce the shallow-clone failure with a depth-1 clone and the project's -W build, then add the post_checkout job the extension's documentation gives for Read the Docs. Build on full history with the project's own command and tox environment, read the footer dates of three pages including one that includes a file from outside docs/, open a page in a browser, and open a pull request with the commands and their 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, pyproject.toml, uv.lock and .readthedocs.yaml. Its description quotes the strict build failing in the shallow clone with the git.too_shallow warning, the same build passing on full history, three footer lines with their dates and the git log line each one matches, and a screenshot of the footer.
A reviewer checks the date format, decides whether to set a time zone, and confirms the post_checkout job runs before the install job on Read the Docs. After merging, every page shows the day its source last changed, and a page whose included file changes picks up that date on the next build.
Run it on every Sphinx project in the terminal
A developer with sphinx-autobuild running sends this body from their own machine with the repository in resources and reads the pull request from the console when the webhook on their API key reports the run. A team with several Sphinx projects sends one request per repository, each with a request_id that is a UUID v5 of the repository's full name, so a script run twice returns the runs already started rather than a second set of pull requests.
Each run reads its own build: a project whose theme overrides the footer gets a template change instead of only a setting, a project built by a GitHub workflow gets fetch-depth: 0 on its checkout step, and a project that pins with pip gets a requirements line instead of a lock update.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The extension is one line in conf.py; the job is everything around it: the lock file a pre-commit hook checks, a theme that may or may not print the line, and a hosted builder whose shallow clone turns the feature into a failed -W build. The agent reproduces that failure in its own sandbox, applies the documented fix for this project's host, and then shows the build passing with real dates, keeping every command and its output in the run's record.
It also reads what the project already decided, a strict build and full control of the Read the Docs steps, and fits the change to it rather than loosening either. Ten projects with ten hosting setups get ten pull requests, each with that project's own checkout fix.
Frequently asked questions
Why not just set html_last_updated_fmt?
On its own it prints the time of the build on every page, so a page untouched for years shows today's date. The extension fills last_updated per page from git, and the format setting then only decides how the date is written.
What does the Read the Docs job do?
Read the Docs clones shallowly, and the extension's documentation says to add a post_checkout job running git fetch --unshallow || true so the commit history is there when Sphinx runs. The trailing || true keeps a build that already has full history from failing on the fetch.
Do pages that include other files get the right date?
Yes. The extension checks each page's dependencies and uses the newest date among them, so the changelog page, which includes the root CHANGES.md, carries the changelog's last commit date, and the agent shows that pair in the pull request.
Will autosummary or generated pages break the build?
A generated page has no tracked source; by default the extension lets it inherit the date of the tracked files it depends on, and git_untracked_check_dependencies = False turns that off. This project generates none, so the pull request only notes the setting.