Roxygen2: Templates and Markdown

[krlmlr]

Template files in man-roxygen don't seem to respect Markdown mode: https://github.com/krlmlr/dplyr/commit/89b892f9aecd850d1484791c6f826b8e7e652a7b#commitcomment-20813612

CC @gaborcsardi.

[kevinushey]

Reproducible example:

setwd(tempdir())
devtools::create("roxlate")
setwd("roxlate")

cat(
    "Roxygen: list(markdown = TRUE)",
    file = "DESCRIPTION",
    sep = "\n",
    append = TRUE
)

dir.create("man-roxygen")

cat(
    "#' @param x This is a link to [stats::rnorm()].",
    file = "man-roxygen/roxlate-rnorm.R",
    sep = "\n"
)

cat(
    "#' Foo.",
    "#'",
    "#' Description. Link: [stats::runif()]",
    "#' @template roxlate-rnorm",
    "#' @export",
    "foo <- function(x) {}",
    file = "R/foo.R",
    sep = "\n"
)

devtools::document()
writeLines(readLines("man/foo.Rd"))

This produces the file:

> writeLines(readLines("man/foo.Rd"))
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/foo.R
\name{foo}
\alias{foo}
\title{Foo.}
\usage{
foo(x)
}
\arguments{
\item{x}{This is a link to [stats::rnorm()].}
}
\description{
Description. Link: \code{\link[stats:runif]{stats::runif()}}
}

Note that the [stats::rnorm()] link was not processed, while the [stats::runif()] one was.

[jayhesselberth]

This looks to be a problem of the global md flag not being set when process_templates is called.

I can achieve the desired behavior for this example by adding a @md tag to the template.

setwd(tempdir())
devtools::create("roxlate")
setwd("roxlate")

cat(
  "Roxygen: list(markdown = TRUE)",
  file = "DESCRIPTION",
  sep = "\n",
  append = TRUE
)

dir.create("man-roxygen")

cat(
  "#' @md",
  "#' @param x This is a link to [stats::rnorm()].",
  file = "man-roxygen/roxlate-rnorm.R",
  sep = "\n"
)

cat(
  "#' Foo.",
  "#'",
  "#' Description. Link: [stats::runif()]",
  "#' @template roxlate-rnorm",
  "#' @export",
  "foo <- function(x) {}",
  file = "R/foo.R",
  sep = "\n"
)

devtools::document()
writeLines(readLines("man/foo.Rd"))

This writes:

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/foo.R
\name{foo}
\alias{foo}
\title{Foo.}
\usage{
foo(x)
}
\arguments{
\item{x}{This is a link to \code{\link[stats:rnorm]{stats::rnorm()}}.}
}
\description{
Description. Link: \code{\link[stats:runif]{stats::runif()}}
}

[gaborcsardi]

@jayhesselberth Thanks for the digging! THis is a good workaround for now.