Skip to content

docs: convert prose .rst files to MyST .md#1246

Merged
Jammy2211 merged 2 commits into
mainfrom
feature/rst-to-myst-md
May 4, 2026
Merged

docs: convert prose .rst files to MyST .md#1246
Jammy2211 merged 2 commits into
mainfrom
feature/rst-to-myst-md

Conversation

@Jammy2211
Copy link
Copy Markdown
Collaborator

Summary

Converts 30 prose documentation pages from reStructuredText to MyST Markdown so they're easier for contributors and AI tools to read and edit. The autosummary-driven docs/api/ and docs/_templates/ files are intentionally left as .rst — their dense directive blocks gain nothing from a MyST colon-fence rewrite, and the autogenerated _autosummary/ stubs are .rst regardless.

Adds dollarmath to myst_enable_extensions in docs/conf.py for the existing math blocks in overview/the_basics.md and science_examples/astronomy.md.

myst-parser was already configured. Sphinx accepts mixed .rst/.md source trees, and toctree entries reference file stems, so no toctree edits were needed.

Part of #1245.

API Changes

None — internal docs only.

Test Plan

  • Read the Docs build passes
  • Local sphinx-build -b html docs docs/_build/html runs cleanly with zero new warnings on converted .md files
Full API Changes (for automation & release notes)

None — this PR only changes documentation source files.

🤖 Generated with Claude Code

Keeps docs/api/*.rst and docs/_templates/*.rst as RST — autosummary-driven
pages don't gain readability from a MyST conversion. Adds `dollarmath` to
myst_enable_extensions for the existing math blocks in overview/the_basics.md
and science_examples/astronomy.md.

Part of #1245.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@Jammy2211 Jammy2211 added the pending-release PR queued for the next release build label Apr 30, 2026
Catches the branch up to main. The 2026.5.1.1 and 2026.5.1.4 release
commits bumped the Colab URL tag in docs/index.rst on main; that file
was deleted in the conversion, so the modify/delete conflict is
resolved by keeping the deletion and porting the bump
(2026.4.13.6 → 2026.5.1.4) to the MyST docs/index.md sibling.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@Jammy2211
Copy link
Copy Markdown
Collaborator Author

Branch caught up to main.

main advanced 13 commits since the conversion — most are unrelated source/test changes (autoarray-side jax cleanup, EP cavity-message factor, etc.). The relevant docs-touching commits were the two automated 2026.5.1.1 and 2026.5.1.4 Colab URL-tag bumps, which modified docs/index.rst (which the conversion deleted). The modify/delete conflict was resolved by keeping the deletion and porting the bump (2026.4.13.62026.5.1.4) to the MyST docs/index.md sibling. See merge commit 2cc8701.

No structural changes — URL-tag substitution only.

@Jammy2211 Jammy2211 merged commit c2f0edc into main May 4, 2026
3 checks passed
@Jammy2211 Jammy2211 deleted the feature/rst-to-myst-md branch May 4, 2026 12:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

pending-release PR queued for the next release build

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant