# Migrate MkDocs API Docs From mkautodoc to mkdocstrings

Yes. An agent rewrites every ::: directive for mkdocstrings, moves the handler options into mkdocs.yml, keeps the same objects documented and builds in strict mode.

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

## What the agent does

The agent clones the repository into its own cloud sandbox and counts what the current extension documents, because the migration is judged by that count. In a project like encode/httpx, `mkdocs.yml` lists `mkautodoc` under `markdown_extensions` beside `admonition` and `codehilite`, with the Material theme and a `custom_dir` override; `requirements.txt` pins `mkdocs==1.6.1`, `mkautodoc==0.2.0` and `mkdocs-material==9.6.18`. `docs/api.md` holds eleven `::: httpx.name` directives, each with a `:docstring:` line and, for `httpx.Client` and `httpx.AsyncClient`, a `:members:` line naming the methods to show; `docs/exceptions.md` holds twenty-eight more. `docs/css/custom.css` styles two classes only mkautodoc produces, `autodoc-docstring` and `autodoc-members`. `scripts/build` runs `mkdocs build` after the package build, and `.github/workflows/test-suite.yml` runs it on every Python from 3.9 to 3.13, so the docs build must install on all of them. On PyPI, 0.2.0 is mkautodoc's latest release, the version pinned here.

It then reads how the docstrings are written, since that decides the handler options. `httpx.get` in `httpx/_api.py` has a short prose docstring with a bold `**Parameters**` line that points at `httpx.request`; `Client` in `httpx/_client.py` has a Markdown bullet list of parameters under `**Parameters:**`. These are not Google or NumPy sections, so mkdocstrings cannot build a parameter table from them, and the agent does not pretend it can: it configures the Python handler to render the docstring as Markdown prose, which is what mkautodoc did, and turns off the source listing. The signatures are long, with unions like `ssl.SSLContext | str | bool`, so it sets `separate_signature` to put each on its own block and keeps annotations on.

The rewrite itself is mechanical and the agent does it with one script so the thirty-nine directives are changed the same way: `::: httpx.get` with `:docstring:` becomes `::: httpx.get` with no option, since the docstring is what mkdocstrings shows by default; `:members: headers cookies params ...` becomes an indented `options:` block with a `members:` list of the same names in the same order, so the `Client` and `AsyncClient` pages keep their method order. In `mkdocs.yml`, `mkautodoc` leaves `markdown_extensions` and a `plugins:` section arrives with `search` listed first, because declaring any plugin turns off the default search unless it is named, and `mkdocstrings` with the Python handler's options under it. `requirements.txt` swaps the `mkautodoc` pin for `mkdocstrings[python]` at the newest release that installs on every interpreter in the CI matrix, which the agent checks by installing it on the oldest one, and the two dead rules leave `custom.css`.

The check is the built site. The agent runs `mkdocs build --strict`, where mkdocstrings fails the build on an identifier it cannot import, so a typo in one of the thirty-nine names stops the run instead of producing an empty section. It builds the site at the base commit too, extracts the headings from `site/api/index.html` and `site/exceptions/index.html` from both builds and diffs them, so the pull request can say which objects are documented before and after, and runs `scripts/check` to show the package itself is untouched.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Migrate this MkDocs site's API reference from mkautodoc to mkdocstrings. Read mkdocs.yml, requirements.txt, every docs page with ::: directives, docs/css/custom.css, scripts/build and the CI workflow's Python matrix first, and count the directives and their options. Read a few of the documented docstrings and choose handler options that render them as the prose they are, without a parameter table they do not have; turn off source listings and separate the signatures. Rewrite every directive with one script: drop :docstring:, turn :members: lines into an options block with a members list in the same order. In mkdocs.yml remove mkautodoc from markdown_extensions and add a plugins section with search first and mkdocstrings with its handler options. Replace the mkautodoc pin in requirements.txt with mkdocstrings[python] at the newest release that installs on every Python version CI runs, and prove it on the oldest. Delete the autodoc CSS rules. Build the site at the base commit and with your change, diff the headings of the API pages, run mkdocs build --strict and the repository's check script, paste the output in the pull request and open it.",
  "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

A pull request that changes `mkdocs.yml`, `requirements.txt`, `docs/api.md`, `docs/exceptions.md` and `docs/css/custom.css`, with every directive rewritten and no change under the package. The description holds the before-and-after heading diff for both reference pages, the `mkdocs build --strict` output, the install check on the oldest interpreter in the matrix, and the handler options with a sentence for each.

A reviewer opens the built `Client` page and compares it with the published one: the same methods in the same order, the bullet list of parameters still readable as prose, the signature on its own block. They then decide the question the migration opens but does not answer: whether to rewrite the docstrings into a style mkdocstrings can turn into tables, which is a change to the package, not to the docs.

They also check the pinned release against the project's own Python floor in `pyproject.toml`, since the docs build runs in the same job as the tests on every version.

## Run it on every docs repository

A team that maintains several projects on the same extension runs this once per repository rather than by hand. A short script on your server lists the repositories and sends one `POST /o/{org}/sessions` per project with this body and that repository in `resources`. Give each request a `request_id`, a UUID made with UUID v5 from the repository name, so a retried run of the script returns the session it already started instead of opening a second pull request. Set a `webhook_url` on the key from the console's Developers page and each `run.completed` event names the session; read the pull request from it.

## Why run it on Rush?

A docs migration is only safe if the same things are documented afterwards, and the only way to know is to build both versions and compare them. The agent does that in its own sandbox, with the pinned MkDocs and theme versions, on the oldest Python the project supports, and runs the strict build that turns a mistyped identifier into a failure instead of a blank heading.

Both builds, the heading diff and the install check stay in the run's transcript at `GET /o/{org}/sessions/{id}/messages`, and the rewritten pages are listed with their diff at `GET /o/{org}/p/{project}/sessions/{id}/changes`. A reviewer who wants to see one rendered page reads the agent's own comparison rather than rebuilding the site locally.

## Frequently asked questions

### Will the docstrings render the same way?

Close to it. mkautodoc inserted the docstring as Markdown; mkdocstrings does the same when its handler is told not to expect Google or NumPy sections, so the bold parameter lists stay as they are. What changes is the signature, which mkdocstrings renders itself, and the heading markup, which the Material theme styles.

### Why does mkdocs.yml need a search entry?

MkDocs enables the `search` plugin only when no `plugins:` section is declared. Adding `mkdocstrings` creates that section, so `search` has to be listed too or the site loses its search box. The agent lists it first.

### What does strict mode catch here?

An identifier that cannot be imported. With mkautodoc a mistyped name produced an empty block; with `mkdocs build --strict`, mkdocstrings reports the name and fails the build, so the thirty-nine directives are checked by the build rather than by eye.

### Why check the oldest Python version?

Because `scripts/build` runs `mkdocs build` inside the test job on every interpreter in the CI matrix. A release of the handler that drops an older Python would pass locally and fail that one job, so the agent installs the pin on the oldest version before choosing it.

## More MkDocs jobs

- [Add a Workflow That Deploys MkDocs Documentation on Every Push](https://getrush.ai/run/add-deploy-workflow/mkdocs/)
- [Add a Strict Docs Build Check to MkDocs Docs](https://getrush.ai/run/add-docs-build-check/mkdocs/)
- [Add Giscus Comments to a MkDocs Material Site](https://getrush.ai/run/add-giscus-comments/mkdocs/)

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

- [Move Firebase Functions From process.env to Params and Secrets](https://getrush.ai/run/migrate-to-params/firebase-functions/)
- [Migrate a Python Library from Pydantic v1 to v2](https://getrush.ai/run/migrate-to-pydantic-v2/pydantic/)
- [Migrate an Angular App to Signal Inputs and Outputs](https://getrush.ai/run/migrate-to-signals/angular/)

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