rst-to-myst [UNDER-DEVELOPMENT]

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]

Basic Usage

Command-Line Interface (CLI)

For all commands see:

rst2myst --help

Parse via stdin:

$ echo ":role:`content`" | rst2myst parse
{role}`content`

Parse via file:

$ rst2myst parse -f path/to/file.rst
...

Warnings are written to stderr and converted text to stdout.

List available directives/roles:

$ rst2myst directives list
acks admonition ...

$ rst2myst roles list
abbr abbreviation ...

Show details of a specific directive/role:

$ rst2myst directives show admonition
class: docutils.parsers.rst.directives.admonitions.Admonition
description: ''
has_content: true
name: admonition
optional_arguments: 0
options:
  class: class_option
  name: unchanged
required_arguments: 1

$ rst2myst roles show abbreviation
description: |-
  Generic interpreted text role, where the interpreted text is simply
  wrapped with the provided node class.
module: docutils.parsers.rst.roles
name: abbreviation

Python Interface (API)

from rst_to_myst import convert

text, stderr_stream = convert("""
Some RST
========

To **convert**
""")

Advanced Usage

You can select a language to translate directive/role names:

$ rst2myst parse -l fr -f path/to/file.rst
...

You can select whether sphinx directives/roles are loaded:

$ rst2myst parse --no-sphinx -f path/to/file.rst
...

You can load directives/roles from extensions:

$ rst2myst parse -e sphinx.ext.autodoc -e sphinx_panels -f path/to/file.rst
...

Directives are converted according to rst_to_myst/data/directives.yml, which can also be updated with an external YAML file, using the -c/--conversions option. This is a mapping of directive import paths to a conversion type:

• "eval_rst" (the default): no conversion, wrap in MyST eval_rst directive

  ```{eval_rst}
  .. name:: argument `link`_
     :option: value
  
     content `link`_
  ```
  

• "direct": convert directly to MyST directive, keeping original argument/content

  ```{name} argument `link`_
  :option: value
  
  content `link`_
  ```
  

• "argument_only": convert to MyST directive and convert the argument to Markdown

  ```{name} argument [link](link)
  :option: value
  
  content `link`_
  ```
  

• "content_only": convert to MyST directive and convert the content to Markdown

  ```{name} argument `link`_
  :option: value
  
  content [link](link)
  ```
  

• "argument_content": convert to MyST directive and convert the content to Markdown

  ```{name} argument [link](link)
  :option: value
  
  content [link](link)
  ```
  

If a conversion type is prepended by "_colon", use ::: delimiters instad of ```, e.g. "argument_content_colon"

:::{name} argument [link](link)
:option: value

content [link](link)
:::

Conversion Notes

The conversion is designed to be fault tolerant, i.e. it will not check if referenced targets, roles, directives, etc exist nor fail if they do not.

The only syntax where some checks are required is matching anonymous references and auto-number/symbol footnotes with their definitions; these definitions must be available.

• enumerated lists with roman numerals or alphabetic prefixes will be converted to numbers
• only one kind of footnote (i.e. no symbol prefixes)
• citation are turned into footnotes, with label prepended by cite_prefix
• inline targets are not convertible (and so ignored)
• If tables are not compatible with Markdown (single header row, no merged cells, etc), then they will be wrapped in an eval_rst
• Markdown blockquotes do not have an attribution syntax, so it is converted instead to <p class="attribution">—text</p> (the standard HTML render)

TODO

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

• line blocks
• field lists (except at top of document, which are converted to front matter)
• option lists

Also custom functions for directive parsing would be desirable.

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.