markdown_to_rst

pyhelpers.store.markdown_to_rst(path_to_md, path_to_rst, reverse=False, engine=None, pandoc_exe=None, verbose=False, **kwargs)[source]

Convert a Markdown file (.md) to a reStructuredText (.rst) file.

This function relies on Pandoc or pypandoc.

Parameters:

  • path_to_md (str | os.PathLike) – path where a markdown file is saved

  • path_to_rst (str | os.PathLike) – path where a reStructuredText file is saved

  • reverse (bool) – whether to convert a .rst file to a .md file, defaults to False

  • engine (None | str) – engine/module used for performing the conversion, defaults to None; an alternative option is 'pypandoc'

  • pandoc_exe (str | None) – absolute path to the executable “pandoc.exe”, defaults to None; when pandoc_exe=None, use the default installation path, e.g. (on Windows) “C:\Program Files\Pandoc\pandoc.exe”

  • verbose (bool | int) – whether to print relevant information in console, defaults to False

  • kwargs – [optional] parameters of subprocess.run (when engine=None) or pypandoc.convert_file (when engine='pypandoc')

Examples:

>>> from pyhelpers.store import markdown_to_rst
>>> from pyhelpers.dirs import cd

>>> dat_dir = cd("tests\documents")
>>> path_to_md_file = cd(dat_dir, "readme.md")
>>> path_to_rst_file = cd(dat_dir, "readme.rst")

>>> markdown_to_rst(path_to_md_file, path_to_rst_file, verbose=True)
Converting "tests\data\markdown.md" to "tests\data\markdown.rst" ... Done.

>>> markdown_to_rst(path_to_md_file, path_to_rst_file, engine='pypandoc', verbose=True)
Updating "readme.rst" at "tests\documents\" ... Done.