rst-to-myst

Convert ReStructuredText to MyST Markdown, and also explore available roles/directives.

See tests/fixtures/render.txt for examples of inputs -> outputs.

Install

pip install rst-to-myst

or with sphinx:

pip install rst-to-myst[sphinx]

To then run a basic conversion of a whole project:

$ rst2myst convert docs/**/*.rst

For greater control, you can pass configuration with CLI options, or via a YAML configuration file:

$ rst2myst convert --config config.yaml docs/**/*.rst

config.yaml:

language: en
sphinx: true
extensions:
- sphinx_panels
default_domain: py
consecutive_numbering: true
colon_fences: true
dollar_math: true
conversions:
    sphinx_panels.dropdpwn.DropdownDirective: parse_all

See the documentation for more information.

Development

This package utilises flit as the build engine, and tox for test automation.

To install these development dependencies:

pip install flit tox

To run the tests:

tox

To run the code formatting and style checks:

pip install pre-commit
pre-commit run --all

Publish to PyPi

Either use flit directly:

flit publish

or trigger the GitHub Action job, by creating a release with a tag equal to the version, e.g. v0.0.1.

Note, this requires generating an API key on PyPi and adding it to the repository Settings/Secrets, under the name PYPI_KEY.

TODO

The conversion covers almost all syntaxes (see https://docutils.sourceforge.io/docs/user/rst/quickref.htm) except:

• line blocks
• option lists

Also custom functions for directive parsing would be desirable.