In Genentech/rd2markdown: Convert Rd Files into Markdown

knitr::opts_chunk$set(echo = TRUE)

The rd2markdown package

Markdown has become a staple markup syntax and is commonly used as an interface in modern developer tools. Markdown is used for READMEs, for static content generation and as a rich text interchange format for language servers. As these use cases become more common, it becomes increasingly important that R provides an interface to its documentation to more seamlessly integrate with these tools.

The rd2markdown itself is a dependency-less, base R centric package that converts .Rd documentation objects into markdown files. This isn't the first package to attempt to solve this problem, but we feel this approach is more robust, extensible and maintainable. We aim to provide a solution that, with a help of the R community, will satisfy requirements set by various use cases and groups.

Functionalities

The rd2markdown package provides tools to conveniently extract the documentation objects and then convert them into standard markdown files. Right now, those functionalities are provided by three functions exported for the end-user.

rd2markdown

Overview

The rd2markdown is the core of the rd2markdown package. This interface is modelled after the tools::Rd2* family of functions, filling the gap in this family of functions to target markdown. It is here, that the actual conversion from .Rd into .md happens. It uses the innovative idea of treating particular Rd tags as classes and dispatching to particular methods accordingly. Thanks to that, most of the common tags have dedicated treatment and can be formatted in various ways. On top of that, such a design ensures trouble-free extensibility of the package, should new tags need to be covered.

rd2markdown can work in various types. It accepts .Rd objects extracted with get_rd option but also can directly fetch documentation topics based on the file path or the package. rd2markdown will leverage this functionality when needed to flexibly convert provided Rd files provided as text, file paths or help aliases. It is worth pointing out that the actual output of rd2markdown function is a character vector of length one that uses special signs to format the document. Use writeLines function to create an actual markdown file using this output.

At the beginning, lets set up the paths for examples files we are going to use throughout the vignette.

rd_files <- c("rd_file_sample.Rd", "rd_file_sample_2.Rd")
rd_examples_path <- system.file("examples", package = "rd2markdown")
rd_examples_macro <- file.path(rd_examples_path, "macros", "macros.Rd")
rd_examples <- file.path(rd_examples_path, rd_files)

Examples

Basic usage with previously extracted documentation

rd <- rd2markdown::get_rd(file = rd_examples[[1]])
md <- rd2markdown::rd2markdown(rd)
cat(md)

The content of the document object can be trimmed to particular sections with fragments parameter. It corresponds to actual R package documentation sections

rd <- rd2markdown::get_rd(file = rd_examples[[1]])
md <- rd2markdown::rd2markdown(rd, fragments = c("description", "usage"))
cat(md)

rd2markdown function can also work with a path to the file taking advantage of the hidden parameter file (and macros if necessary)

md <- rd2markdown::rd2markdown(file = rd_examples[[1]])
cat(md)

md <- rd2markdown::rd2markdown(
  file = rd_examples[[2]],
  macros = rd_examples_macro # Use macros = NA to automatically discover macros
  )  
cat(md)

or take documentation object directly from the package with a help of topic and package

md <- rd2markdown::rd2markdown(
  topic = "rnorm",
  package = "stats",
  fragments = c("description", "usage")
)

cat(md)

get_rd

Overview

The get_rd function actually extracts the .Rd file from the file or directly from the package. It can be used on its own, but also rd2markdown function u ses it internally. The function itself is using the base function tools::parse_Rd and base::help to extract the documentation while escaping errors with graceful exceptions handling. The function is passing file and macros parameters directly to tools::parse_Rd with one small addition to how macros work. If it is NA, then the get_rd will try to locate macros directory in the same directory the file is and take the first .Rd file in alphabetical order, as tools::parse_Rd accepts only a single file as a macro.

Examples

Extracting documentation directly from the .Rd file and file parameter

rd2markdown::get_rd(file = rd_examples[[1]])

reaching out to the installed package to fetch documentation using topic and package parameters while keeping file as NULL

rd2markdown::get_rd(topic = "rnorm", package = "stats")

using macros parameter to pass a custom macro that is used while extracting the documentation

rd2markdown::get_rd(
  file = rd_examples[[2]],
  macros = rd_examples_macro
)

or macros to try to automatically discover macros

rd2markdown::get_rd(
  file = rd_examples[[2]],
  macros = NA
)

documentation_to_markdown

Overview

The documentation_to_markdown function merges both and rd2markdown and get_rd, providing a vectorized way of parsing multiple documentation files at once. Simply pass a vector of paths and the function will return a named list of markdown documents created with rd2markdown function.

Examples

It is enough to pass the vector of file paths to get a list of parsed markdown files

rd2markdown::documentation_to_markdown(rd_examples)

The documentation_to_markdown function also allows extracting only particular parts of the documentation, using fragments parameter. If a given documentation file does not have a specific section, it will become an empty string.

rd2markdown::documentation_to_markdown(rd_examples, fragments = "details")

Summary

The rd2markdown package is an attempt to solve the issue of converting R package documentation objects into readable markdown documents. It is still in early development, so not every single aspect or nuance is covered. Therefore, we would like to welcome community contribution by reporting gaps by opening issues on https://github.com/genentech/rd2markdown and describing the problem or missing functionality. We value any type of input as we aim to provide a tool that will be possible to use in various R applications.

Genentech/rd2markdown documentation built on Feb. 28, 2025, 1:27 p.m.