Rmdawn: a Python package for programmatic R markdown workflows — Rmdawn 0.0.1 documentation

# 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://marskar.github.io/rmdawn/.

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

## Installation

    pip install rmdawn

or clone the repo, e.g. `git clone https://github.com/marskar/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 `#`.