Skip to content

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

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

docs: convert prose .rst files to MyST .md#383
Jammy2211 merged 2 commits intomainfrom
feature/rst-to-myst-md

Conversation

@Jammy2211
Copy link
Copy Markdown
Collaborator

Summary

Converts 23 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 substitution to myst_enable_extensions in docs/conf.py for substitution blocks present in the converted prose.

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 PyAutoLabs/PyAutoFit#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 `substitution`
to myst_enable_extensions for existing substitution blocks.

Part of PyAutoLabs/PyAutoFit#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 several .rst files on main; those
files were deleted in the conversion, so the modify/delete conflicts
are resolved by keeping the deletion and porting the bump
(2026.4.13.6 → 2026.5.1.4) to the MyST .md siblings:

- docs/index.md
- docs/howtogalaxy/chapter_1_introduction.md
- docs/howtogalaxy/chapter_2_modeling.md
- docs/howtogalaxy/chapter_3_search_chaining.md
- docs/howtogalaxy/chapter_4_pixelizations.md
- docs/howtogalaxy/chapter_optional.md
- docs/overview/overview_2_new_user_guide.md

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 7 commits since the conversion. The two automated 2026.5.1.1 and 2026.5.1.4 Colab URL-tag bumps modified docs/index.rst, all docs/howtogalaxy/chapter_*.rst, and docs/overview/overview_2_new_user_guide.rst — files the conversion deleted. The modify/delete conflicts were resolved by keeping the deletions and porting the bump (2026.4.13.62026.5.1.4) to the seven matching MyST .md siblings:

  • docs/index.md
  • docs/howtogalaxy/chapter_1_introduction.md
  • docs/howtogalaxy/chapter_2_modeling.md
  • docs/howtogalaxy/chapter_3_search_chaining.md
  • docs/howtogalaxy/chapter_4_pixelizations.md
  • docs/howtogalaxy/chapter_optional.md
  • docs/overview/overview_2_new_user_guide.md

See merge commit 8e577a8. No structural changes — URL-tag substitution only.

@Jammy2211 Jammy2211 merged commit 8af43f8 into main May 4, 2026
5 checks passed
@Jammy2211 Jammy2211 deleted the feature/rst-to-myst-md branch May 4, 2026 12:05
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