All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

More jobs like this: Hand off a long task

Keep reading