Skip to main content

Convert RST to MyST-Markdown.

Project description

rst-to-myst

Build Status codecov.io PyPI version

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: https://rst-to-myst.readthedocs.io/

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rst_to_myst-0.4.0.tar.gz (37.8 kB view hashes)

Uploaded Source

Built Distribution

rst_to_myst-0.4.0-py3-none-any.whl (36.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page