# Migrate a Sphinx Project From m2r to m2r2

Yes. An agent swaps the archived m2r extension for m2r2 in your requirements and conf.py, rebuilds the docs and compares the pages that include Markdown.

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

## What the agent does

m2r lets a Sphinx project pull Markdown into reStructuredText pages, most often the README through an `mdinclude` directive. Its repository, miyakogi/m2r, is archived, and it has fallen behind the libraries under it in three separate ways. Release 0.2.1 with a current mistune stops at `AttributeError: module 'mistune' has no attribute 'BlockGrammar'`. The same release with a current docutils stops earlier, at `ImportError: cannot import name 'ErrorString' from 'docutils.core'`. The last release, 0.3.1, declares `mistune<2` and so installs, but `mdinclude` then fails with `AttributeError: module 'docutils.nodes' has no attribute 'reprunicode'` on docutils 0.22. Which message a project sees depends only on what pip resolved that day. m2r2, kept at CrossNox/m2r2, is the fork that follows current Sphinx.

megvii-research/hpman is a typical project to migrate. `docs/requirements.txt` has three unpinned lines, `m2r`, `sphinx` and `sphinx-rtd-theme`. `docs/conf.py` lists `"m2r"` in `extensions` after five `sphinx.ext` modules, and `docs/index.rst` contains `.. mdinclude:: ../README.md`, so the whole landing page of the documentation is the README passed through m2r. `.readthedocs.yml` installs `docs/requirements.txt` with the Python version line commented out, and `requirements.dev.txt` names m2r a second time for local builds. A fresh install of that file today gives m2r 0.3.1, Sphinx 9 and docutils 0.22, and a build that reaches `mdinclude` fails on `reprunicode`.

The agent reproduces that before editing. It creates a clean environment, installs `docs/requirements.txt`, and runs the build the way the project does: here `docs/gendoc.sh`, which calls `sphinx-apidoc -f -o api ../hpman` and then `make SPHINXOPTS="-n" html`. With the failure recorded, the migration is three edits. `m2r` becomes `m2r2` in both requirements files, and `"m2r"` becomes `"m2r2"` in `extensions`. The directive keeps its name, `mdinclude`, and so do the options a `conf.py` may set, such as `m2r_parse_relative_links` and `m2r_anonymous_references`; the agent checks the names against the installed package instead of renaming them by pattern. It also searches for the two other places m2r hides: a `from m2r import` in `setup.py` that builds a long description, and an `m2r` command in a Makefile or script.

Then it rebuilds and looks at the output, because a build that exits zero can still render a page differently. m2r2 parses Markdown with mistune 3, a different parser from the mistune 0.8 that m2r used. The agent builds once more with the old extension in a second environment held on docutils 0.20.1, where m2r 0.3.1 still works, and compares the HTML of each page that includes Markdown: headings, tables, code fences, nested lists, and the README's badge images and relative links. Differences are listed with the Markdown that caused them. Warnings matter too. This project builds with `-n`, Sphinx's nitpicky mode, so a new broken reference appears in the build log and the agent reports each one.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "This project's Sphinx documentation uses the m2r extension, which is archived and fails on current docutils and mistune (for example \"module 'mistune' has no attribute 'BlockGrammar'\" or \"module 'docutils.nodes' has no attribute 'reprunicode'\"). Migrate it to m2r2. First find every use of m2r: requirements and constraints files, setup.py and pyproject.toml extras, the extensions list and any m2r_* options in conf.py, mdinclude directives and .md sources in the docs tree, imports of m2r in Python code, and m2r commands in Makefiles, scripts, CI and the Read the Docs configuration. In a clean environment install the docs dependencies as the project does and run its real docs build command; keep the failing output. Then replace m2r with m2r2 in every dependency file, change the extension name in conf.py, update imports and command names, and keep directive and option names that m2r2 still accepts (check them against the installed m2r2, do not guess). Rebuild with the same command and the same flags. For comparison, build the old configuration in a second environment with m2r 0.3.1 and docutils below 0.21, and compare the generated HTML for every page that includes Markdown; list each visible difference with the Markdown that caused it. Report every new warning. Do not pin Sphinx or docutils to old versions as the fix, do not convert Markdown files to reStructuredText, and do not change the theme. If the docs build runs in CI or on Read the Docs, say what Python version it uses and whether m2r2 supports it. Open a pull request with the failing output, the passing output and the list of rendering differences.",
  "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 small pull request: one changed line per requirements file and one in `conf.py`, plus any import or command the search turned up. The description starts with the build output on the old extension, ending in whichever of the three errors the project hits, and the output of the same command after the change.

The second half is the rendering comparison. For each page that includes Markdown the agent states whether the HTML matches the old build and, where it does not, shows the affected fragment before and after with the source lines. A typical entry is a table or a nested list that mistune 3 reads differently. Where the fix belongs in the Markdown, such as a blank line before a list, the agent proposes it in the same pull request as a separate commit so it can be reviewed or dropped on its own.

A reviewer opens the built pages for the README include and one page with code blocks, and reads the warning list. If the project publishes on Read the Docs, the last check is there: the pull request names the Python version the configuration selects, and if pull request previews are enabled for the project, the preview build confirms the hosted environment resolves the same packages.

## Run it on every Monday morning

Documentation dependencies are usually unpinned, so they drift without a commit and break on a publish day. A weekly automation with a `schedule` trigger, its `cron` set to Monday morning in your `timezone`, can run in the Project that holds the repository with a prompt that installs the docs requirements fresh, builds, and opens a pull request only when the build fails or warns. An automation run counts against the automation's own `max_runs_per_hour`, not a key's limits.

For many repositories at once, a script on your side is simpler: list the repositories whose docs requirements name m2r, and send the request above once per repository with your API key. Give each a `request_id` that is a UUID v5 of the repository name and the week, so running the script twice does not open duplicate pull requests. Runs beyond the key's `max_concurrent` wait as `queued` and start as slots free.

## Why run it on Rush?

The migration itself is three lines. What takes time is building the documentation twice, in two environments that must not contaminate each other, and reading the output side by side. On a laptop that means two virtualenvs, a docs toolchain you may not have, and the temptation to check one page and call it done. In a Rush sandbox the agent builds both, compares every page that includes Markdown, and the commands and output stay in the session transcript.

Docs builds also fail in ways that only show on a clean machine. An old `_build` directory or a cached environment can make a broken configuration look healthy. The sandbox starts empty, the install comes straight from the requirements file, and the result is the one your hosting service will get on its next build.

## Frequently asked questions

### Do I have to rename my mdinclude directives?

No. m2r2 registers the directive under the same name, and it keeps the `m2r_`-prefixed options in `conf.py`. The lines that change are the package name in your requirements and the entry in `extensions`. Python code that imports `m2r` and scripts that call the `m2r` command change to `m2r2`.

### Can I just pin mistune or docutils instead?

For a while. m2r 0.3.1 with docutils 0.20.1 still builds, and failed in the same test with docutils 0.21.2 and 0.22. Holding docutils back also holds back Sphinx, and the archived project will not get a fix. The agent treats old pins as a stopgap and does the migration.

### Will my pages look the same after the switch?

Mostly, and that is why the run compares them. m2r2 uses a newer Markdown parser, and edge cases such as nested lists, tables and raw HTML can come out differently. The pull request lists every difference it found in the built HTML so you are not discovering them on the published site.

### Should I move to MyST instead?

MyST is the more common choice for new Sphinx projects that write Markdown, and it is a different kind of change: the directive syntax differs and included files may need edits. If your only use is including a README, m2r2 is the smaller step. Ask for the MyST migration as its own run when you want it.

## More jobs like this: Upgrade dependencies weekly

- [Migrate a React App From Material-UI v4 to MUI v5](https://getrush.ai/run/migrate-material-ui-to-mui/material-ui/)
- [Migrate From mgo to the Official MongoDB Go Driver](https://getrush.ai/run/migrate-mgo-to-mongo-go-driver/mgo/)
- [Replace minimist With util.parseArgs in a Node.js CLI](https://getrush.ai/run/migrate-minimist-to-parseargs/minimist/)
- [Migrate From mitchellh/mapstructure to go-viper/mapstructure v2](https://getrush.ai/run/migrate-mitchellh-mapstructure-to-go-viper/mapstructure/)
- [Replace the mock Backport With unittest.mock](https://getrush.ai/run/migrate-mock-to-unittest-mock/mock/)
- [Migrate From mysql to mysql2 in a Node.js App](https://getrush.ai/run/migrate-mysql-to-mysql2/mysql/)

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