Enable non-R knitr engines

[nbenn]

I'm trying to include a TikZ image in the docs of a package of mine. While looking at my options, i was delighted to see that roxygen2 supports knitr code chunks. Combined with the tikz engine support of knitr I thought I had all I needed to make this work. Unfortunately, currently there is a quite restrictive check in place for what is considered a knitr code chunk

roxygen2/R/markdown.R

Lines 73 to 77 in c73def4

	is_markdown_code_node <- function(x) {
	info <- str_sub(xml_attr(x, "info"), 1, 3)
	str_sub(xml_text(x), 1, 2) == "r " ||
	(!is.na(info) && info %in% c("{r ", "{r}", "{r,"))
	}

Playing around with this a bit, I was seamlessly able to generate my TikZ image from code simply by relaxing this check a bit by including other knitr engines as reported by knitr::knit_engines$get().

markdown_engine_regexp <- function() {
  opts <- c("r", names(knitr::knit_engines$get()))
  paste0("^\\{(", paste(opts, collapse = "|"), ")[, \\}]")
}

is_markdown_code_node <- function(x) {
  info <- xml_attr(x, "info")
  regx <- markdown_engine_regexp()
  str_sub(xml_text(x), 1, 2) == "r " ||
    (!is.na(info) && grepl(regx, info))
}

See also: master...nbenn:master

While I realize that knitr support in roxygen2 is a new and somewhat experimental addition, I was wondering whether you are open to expanding this powerful feature by allowing non-R language engines to be run. I'm happy to submit a PR if this is the case.

[hadley]

@nbenn just to be clear, you're suggesting that we just need to relax our restriction a little and more knitr engines should work?

[nbenn]

Yes, that was precisely my suggestion. Currently knitr chunks are identified by checking whether some first 3 characters are in c("{r ", "{r}", "{r,"), thereby only allowing the "r" knitr engine. I think this could be relaxed to further knitr engines (maybe even all available), making possible for example the inclusion of a TikZ figure in roxygen2 generated docs (which I personally would find an awesome feature).

[gaborcsardi]

I think it is fine to allow other engines as well for code fences. Inline code is more problematic, though.

[gadenbuie]

An additional use case: the new-ish verbatim knitr engine would be perfect for including snippets of R Markdown documents in documentation. Currently it requires @includeRmd or the verbatim chunk will be silently dropped or mangled.

[gaborcsardi]

@gadenbuie I am not sure what you mean exactly, but if you want to escape code fences, then use can use four tick marks for that in commonmark, and thus in roxygen2:

#' ````
#' ```{r}
#' # comment
#' this <- 10
#' is <- this + 10
#' good <- this + is
#' ```
#' ````

[gadenbuie]

Sorry, I've since realized the missing code I'm seeing is actually #1350

[gadenbuie]

Still, verbatim could be useful since it would allow you to store the Rmd snippet somewhere and then include it via the file chunk option

#' ```{verbatim file="man/fragments/example.Rmd"}
#' ```

<!-- man/fragments/example.Rmd -->
```{r}
# comment
this <- 10
is <- this + 10
good <- this + is
```

[cderv]

@gadenbuie the embed engine would be a good fit here too - same as verbatim but adds a highlighting language to the chunk

```{embed}
man/fragments/example.Rmd
```

would produce

````md
```{r}
# comment
this <- 10
is <- this + 10
good <- this + is
```
````

but maybe highlighting is not supported for Markdown in rogygen2 though