Templates and Markdown

[krlmlr]

Template files in man-roxygen don't seem to respect Markdown mode: krlmlr/dplyr@89b892f#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.