In Genentech/rd2markdown: Convert Rd Files into Markdown

knitr::opts_chunk$set(message = FALSE, warning = FALSE, fig.align = 'center', fig.path = "man/figures/")

markdown_output <- function(x, ...) {
  res <- paste(">", strsplit(x, "\n")[[1L]], collapse = "\n")
  knitr::asis_output(res)
}

rd2markdown

Overview

The rd2markdown package provides a way to conveniently convert .Rd package documentation files into markdown files. Documentation can be acquired in various ways, for instance using the documentation page of an already installed package, or by fetching it directly from the source file. The package aims to help other developers in presenting their work, by converting documentation of their packages to markdown files that later can be funneled into a report, README, and any others. Therefore there are countless different scenarios where this tool might be useful. We plan to drive the development of rd2markdown in a way it will address the needs of the R community.

The core logic behind the whole conversion is treating each rd tag as a separate class. We take the documentation object and parse it layer by layer like an onion. Thanks to that, each tag receives a dedicated treatment so it can be presented basically according to the demand. On top of that, it makes the package way more extensible, as adding the support of a new tag is essentially just implementing another method.

Installation

Install the development version from GitHub:

remotes::install_github("Genentech/rd2markdown")

or latest CRAN version

install.packages("rd2markdown")

Examples

Below are some basic examples that show the core functionalities of the rd2markdown, its strong sides and possibilities it provides for the R community.

Rendering from file path

rd_example <- system.file("examples", "rd_file_sample.Rd", package = "rd2markdown")
rd <- rd2markdown::get_rd(file = rd_example)
rd2markdown::rd2markdown(rd, fragments = c("title", "description", "details"))

Rendering from help alias

rd2markdown::rd2markdown(
  topic = "rnorm",
  package = "stats",
  fragments = c("title", "description", "usage")
)

To see the examples showing the complexity of the package, please take a look at the vignette attached in this package The rd2markdown package intro. You will find there not only examples for all exported functions with various combinations of parameters, but also the rationale for this package, why it was created, and what logic it follows.