markdown_to_rst

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

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

This function relies on Pandoc or pypandoc, given the specified engine.

Parameters:

  • path_to_md (str | os.PathLike) – The path where the Markdown file is saved.

  • path_to_rst (str | os.PathLike) – The path where the reStructuredText file will be saved.

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

  • engine (None | str) –

    The engine/module used for performing the conversion; if engine=None (default), the function utilises Pandoc, 'pypandoc' otherwise.

  • pandoc_exe (str | None) – The path to the executable “pandoc.exe”; If pandoc_exe=None (default), the default installation path will be used, e.g. “C:\Program Files\Pandoc\pandoc.exe” (on Windows).

  • verbose (bool | int) – Whether to print relevant information to the console; defaults to False.

  • raise_error (bool) – Whether to raise the provided exception; if raise_error=False (default), the error will be suppressed.

  • kwargs – [Optional] Additional parameters for the function pypandoc.convert_file() (if 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, "readme1.md")
>>> path_to_rst_file = cd(dat_dir, "readme1.rst")
>>> markdown_to_rst(path_to_md_file, path_to_rst_file, verbose=True)
Converting ".\tests\documents\readme.md" to ".\tests\documents\readme.rst" ... Done.
>>> markdown_to_rst(path_to_md_file, path_to_rst_file, engine='pypandoc', verbose=True)
Updating "readme.rst" at ".\tests\documents\" ... Done.