Rmdawn: a Python package for programmatic R markdown workflows

Introduction

The rmdawn Python package allows you to (de)construct, convert, and render R Markdown (Rmd) files in

• your terminal (e.g. bash, zsh, fish, etc.) or
• your favorite Python environment (e.g. PyCharm or Visual Studio Code).

The rmdawn Python package consists of 6 shell commands and functions:

• rmdawn, which concatenates input files to generate an Rmd file.
• rmdusk, which extracts 1) a YAML file, 2) Python or R scripts and 3) Markdown (md) files from Rmd files.
• rmdtor, which converts Rmd files into R scripts using knitr::purl.
• rtormd, which converts R scripts into Rmd files using knitr::spin.
• render, which creates rendered versions of R scripts or Rmd files into HTML, PDF, Word, and other output file formats.
• catren, which combines the functionality of rmdawn and render to generate an Rmd file from source files and then create an output file.

All rmdawn functions and commands, except for rmdawn and rmdusk, rely on the rpy2 Python library. The command line interface relies on the click Python library.

For a related package that provides programmatic tools for working with Jupyter Notebooks, check out the Nbless Python package.

Documentation and Code

The documentation is hosted at https://py4ds.github.io/rmdawn/.

The code is hosted at https://github.com/py4ds/rmdawn.

Installation

pip install rmdawn

or clone the repo, e.g. git clone https://github.com/py4ds/rmdawn and install locally using setup.py (python setup.py install) or pip (pip install .).

Creating an R markdown file with the rmdawn shell command

rmdawn header.yml intro.md scrape.py plot.R notes.txt > example.Rmd

Instead of redirecting to a file (>), you can use the --out_file or -o flag:

rmdawn header.yml intro.md scrape.py plot.R notes.txt -o example.Rmd

The easiest way to handle large numbers of files is to use the * wildcard in the shell.

rmdawn source_file* -o example.Rmd

Extract YAML, markdown, and code files from R markdown files with the rmdusk shell command

rmdusk example.Rmd

Convert between R markdown and R code files with the rmdtor and rtormd shell commands

rmdtor example.Rmd

rtormd example.R

You can also specify an new filename with --out_file or -o flag.

rmdtor example.Rmd -o new.R

rtormd example.R -o new.Rmd

Render R markdown and R code files with the render shell command

The default output format is HTML.

render example.Rmd
render example.R

You can specify output format with the --format or -f flag.

render example.Rmd -f word_document
render example.R -f word_document

If you only specify output filename with the --out_file or -o flag, render will try to infer the output format from the file extension. This will not work for slides or R markdown notebooks.

render example.Rmd -o example.pdf
render example.R -o example.pdf

Create an R markdown file from source files with the catren shell command

You can pass --rmd_file (-r), --out_file (-o), and --format (-f) arguments to catren.

The default output format is HTML.

catren header.yml intro.md scrape.py plot.R notes.txt -r example.Rmd

If you only specify an output filename with the --out_file or -o flag, catren will try to infer the R markdown file name and output format from the file extension.

catren header.yml intro.md scrape.py plot.R notes.txt -o example.pdf

If you only specify an output format with the --format or -f flag or do not provide any optional arguments, catren will create a temporary file in a temporary location.

catren header.yml intro.md scrape.py plot.R notes.txt -f word_document
catren header.yml intro.md scrape.py plot.R notes.txt

Basic usage: Python environment

from pathlib import Path

from rmdawn import rmdawn
from rmdawn import rmdusk
from rmdawn import rtormd
from rmdawn import rmdtor
from rmdawn import render
from rmdawn import catren

# Create an R markdown file from source files
file_list = ["header.yml", "intro.md", "scrape.py", "plot.R", "notes.txt"]
Path("example.Rmd").write_text(rmdawn(file_list))

# Extract source files from an R markdown file
rmdusk("example.Rmd")

# Convert R markdown files into R scripts
rmdtor("example.Rmd")

# Convert R scripts into R markdown files
rtormd("example.R")

# Generate output files from R scripts or R markdown files
render("example.Rmd") # The default format is HTML
render("example.R") # The default format is HTML
render("example.Rmd", out_format="pdf_document")
render("example.R", out_format="word_document")

# Create an R markdown file from source files output files and render it
file_list = ["header.yml", "intro.md", "scrape.py", "plot.R", "notes.txt"]
catren(file_list, rmd_file="example.Rmd") # The default format is HTML
catren(file_list, rmd_file="example.Rmd", out_format="pdf_document")
catren(file_list, out_file="example.html")

# Another alternative is to import the package and use it as a namespace.
import rmdawn

rmdawn.rmdawn(["header.yml", "intro.md", "scrape.py", "plot.R", "notes.txt"])
rmdawn.rmdusk("example.Rmd")
rmdawn.rtormd("example.R")
rmdawn.rmdtor("example.Rmd")
rmdawn.render("example.Rmd") # The default format is HTML

Next Steps

Currently, xaringan slides require a special format.

• Write remark/demark functions and commands to add/remove slide delimiters --- before headers #.