Package 'roxygen2md'

Searches plain Rd in R source files

Description

Looks for Rd-like code in roxygen2 comments, especially useful after running roxygen2md(). This function is designed for interactive use.

Usage

find_rd()

Value

A tidy data frame that has a print() method that also interacts with the RStudio API.

Examples

if (interactive()) {
  # Show remaining Rd syntax after conversion.
  find_rd()
}

---

Convert text to Markdown

Description

Converts a character vector from Rd to Markdown.

The scope argument controls the depth of the transformation.

With scope = "none", no transformations are carried out. The only effect is that Markdown is enabled for this package.

With scope = "simple", the following elements are converted:

• ⁠\\code{}⁠

• ⁠\\emph{}⁠

• ⁠\\bold{}⁠ and ⁠\\strong{}⁠

• ⁠\\href{}⁠

• ⁠\\url{}⁠

With scope = "full", the following elements are converted in addition:

• ⁠\\code{\link{}}⁠ and ⁠\\link{}⁠, with ⁠[]⁠ options

• ⁠\\linkS4class{}⁠

With scope = "unlink", only the following elements are translated:

• ⁠\\link{...}⁠ to ...

With scope = "indent", ⁠@param⁠ and ⁠@return⁠ tags spanning multiple lines are indented with two spaces.

Usage

markdownify(text, scope = c("full", "simple", "unlink", "indent", "none"))

Arguments

text	A character vector containing .Rd style annotations.
scope	The scope of transformations: "simple" runs only transformations that shouldn't substantially change the resulting .Rd files, "full" runs all transformations. In larger packages, run "none", double-check and track the changes, and then run "simple" and then "full".

Value

The same vector with .Rd style annotations converted to Markdown style annotations.

Examples

text <- c(
  "Both \\emph{italics} and \\bold{bold} text.",
  paste0("We can also convert code: \\", "code{\\", "link{identity}}.")
)

text
markdownify(text)

---

Convert from Rd to Markdown in roxygen2 comments

Description

Performs various substitutions in all .R files in a package to make use of the Markdown functionality in roxygen2. This function is designed for interactive use, see markdownify() for details on the transformations. Also attempts to enable Markdown support in roxygen2 by adding a field to DESCRIPTION. Carefully examine the results after running this function!

Usage

roxygen2md(scope = c("full", "simple", "unlink", "indent", "none"))

Arguments

scope

The scope of transformations: "simple" runs only transformations that shouldn't substantially change the resulting .Rd files, "full" runs all transformations. In larger packages, run "none", double-check and track the changes, and then run "simple" and then "full".

Value

List of changed files, invisibly

Examples

if (interactive()) {
  # Convert roxygen to Markdown in one run
  roxygen2md()
}

# Alternatively, convert in three steps:
if (interactive()) {
  # 1. Enable Markdown processing
  roxygen2md("none")

  menu("Please examine/commit the changes and press 1 <enter> to continue.")

  # 2. Convert simple markup
  roxygen2md("simple")

  menu("Please examine/commit the changes and press 1 <enter> to continue.")

  # 3. (Optionally) Remove some of the \code{} expressions
  roxygen2md("unlink")

  menu(paste0(
    "Please remove all unwanted changes, commit the wanted ones, ",
    "and press 1 <enter> to continue."
  ))

  # 4. Convert everything, including links
  roxygen2md("full")
}

---