Skip to content

Latest commit

 

History

History
209 lines (152 loc) · 6.8 KB

README.md

File metadata and controls

209 lines (152 loc) · 6.8 KB
Raw

M2R3

PyPI PyPI version Documentation

M2R3 converts a markdown file including reStructuredText (rst) markups to a valid rst format.

M2R3: "The Return of the Jedi"

M2R3 is a fork of m2r2 which is a fork of m2r.

The reason for m2r3 is that:

Unfortunately I'm going to have to release our version to pypi as we need it to build our project for an urgent release (we were using poetry git= requirements before) but doesn't work on pypi release. Happy to take it down if we integrate the changes and deploy a newer version of m2r2.

From m2r2 to m2r:

They hadn't been updated for a long time and there's been no response from the author about a PR fixing a serious issue that broke several pipelines using sphinx3. Every m2r config should work out of the box. I've changed some of the tooling for what I'm mostly using now. Below goes the original readme, changing only what's needed to work with m2r2.

Main Updates in m2r3:

  • IMPORTANT NOTE: it doesn't fully work, it just mostly works and I intend to keep adding any PRs that come my way. Not all the old functionality is there, but it's mostly there and builds.
  • Updated packaging to poetry, because it was a big pain to reproduce the original package development and this way it's easier to have a reproducible working environment.
  • Update python to the present, works with the latest sphinx versions and mistune v2.
  • Integration of pydantic for type checking and validation of the docstrings.

Old Documentation

Why another converter?

I wanted to write sphinx document in markdown, since it's widely used now and easy to write code blocks and lists. However, converters using pandoc or recommonmark do not support many rst markups and sphinx extensions. For example, rst's reference link like see `ref`_ (this is very convenient in long document in which same link appears multiple times) will be converted to a code block in HTML like see <code>ref</code>_, which is not expected.

Features

  • Basic markdown and some extensions (see below)
    • inline/block-level raw html
    • fenced-code block
    • tables
    • footnotes ([^1])
  • Inline- and Block-level rst markups
    • single- and multi-line directives (.. directive::)
    • inline-roles (:code:`print(1)` ...)
    • ref-link (see `ref`_)
    • footnotes ([#fn]_)
    • math extension inspired by recommonmark
  • Sphinx extension
    • add markdown support for sphinx
    • mdinclude directive to include markdown from md or rst files
    • option to parse relative links into ref and doc directives (m2r_parse_relative_links)
    • option to render mermaid blocks as graphs with sphinxcontrib.mermaid (m2r_use_mermaid, default: auto)
      • auto means that m2r2 will check if sphinxcontrib.mermaid has been added to the extensions list
  • Pure python implementation
    • pandoc is not required

Installation

TODO update more than here.

pip install m2r3

Or

python3 -m pip install m2r3

Usage

Command Line

m2r2 command converts markdown file to rst format.

m2r2 your_document.md [your_document2.md ...]

Then you will find your_document.rst in the same directory.

Programmatic Use

Import m2r2.convert function and call it with markdown text. Then it will return converted text.

from m2r3 import convert

rst = convert('# Title\n\nSentence.')
print(rst)
# Title
# =====
#
# Sentence.

Or, use parse_from_file function to load markdown file and obtain converted text.

from m2r3 import parse_from_file

output = parse_from_file('markdown_file.md')

This is an example of setup.py to write README in markdown, and publish it to PyPI as rst format.

readme_file = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'README.md')
try:
  from m2r3 import parse_from_file

  readme = parse_from_file(readme_file)
except ImportError:
  # m2r3 may not be installed in user environment
  with open(readme_file) as f:
    readme = f.read()
setup(
  ...,
  long_description=readme,
  ...,
)

Sphinx Integration

In your conf.py, add the following lines.

extensions = [
    ...,
    'm2r3',
]

# source_suffix = '.rst'
source_suffix = ['.rst', '.md']

Write index.md and run make html.

When m2r2 extension is enabled on sphinx and .md file is loaded, m2r2 converts to rst and pass to sphinx, not making new .rst file.

mdinclude directive

Like .. include:: file directive, .. mdinclude:: file directive inserts markdown file at the line.

Note: do not use .. include:: file directive to include markdown file even if in the markdown file, please use .. mdinclude:: file instead.

Restrictions

  • In the rst's directives, markdown is not available. Please write in rst.
  • Column alignment of tables is not supported. (rst does not support this feature)
  • Heading with overline-and-underline is not supported.
    • Heading with underline is OK
  • Rst heading marks are currently hard-coded and unchangeable.
    • H1: =, H2: -, H3: ^, H4: ~, H5: ", H6: #

If you find any bug or unexpected behaviour, please report it to Issues.

Example

See example document and its source code.

Note from the original author: I'm using m2r for writing user guide of WDOM. So you can see it as another example. Its HTML is here, and its source code is here.

Demo editor

Note: This hasn't received any updates.

Demo editor of m2r is available. If you are interested in m2r, please try it.

https://github.com/miyakogi/m2rdemo

Dev install

Please install the dev dependencies and pre-commit hooks with:

pip install -r requirements-dev.txt
pre-commit install

Acknowledgement

m2r is written as an extension of mistune, which is highly extensible pure-python markdown parser. Without the mistune, I couldn't write this. Thank you!

Licence

MIT