# Add Last Updated Dates to Sphinx Docs

Yes. An agent dates each Sphinx page by its last git commit with sphinx-last-updated-by-git, keeps the -W build and Read the Docs green, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-last-updated-dates/sphinx/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

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 `.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.

## 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.

## More Sphinx jobs

- [Check for Broken Links in Sphinx Docs with the linkcheck Builder](https://getrush.ai/run/add-link-checking/sphinx/)
- [Add llms.txt to a Sphinx Docs Site](https://getrush.ai/run/add-llms-txt/sphinx/)
- [Add Mermaid Diagrams to Sphinx Docs](https://getrush.ai/run/add-mermaid-diagrams/sphinx/)

## The same job on other stacks

- [Add Last Updated Dates to a VitePress Blog](https://getrush.ai/run/add-last-updated-dates/vitepress/)
- [Show Last Updated Dates on a Zola Blog](https://getrush.ai/run/add-last-updated-dates/zola/)
- [Add Last Updated Dates to an mdBook Site](https://getrush.ai/run/add-last-updated-dates/mdbook/)

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