build_readme() rejects (and fails with) HTML-based output

[ian-curtis]

Description of Problem

I am working on building a package that is designed for a rather narrow audience. Part of the package generates plots (ggplots, to be specific) and I have no problem with these. The other part of the package generates flextable objects.

Edit: here is the package

From what I understand, build_readme() generates plots and saves them as images, saving them to the man/figures/ directory for use by the README.md. However, I do not see this type of behavior with HTML content, such as my flextables (and I assume this also applies to kables. It seems that gitHub-flavored markdown does not like many HTML tags, including <style> so my table outputs are not rendered at all when converting from README.Rmd to README.md.

I'm not sure if this is a true "issue" with the package or if I just need to think outside of the box a little. But, in my head, I'd love it if build_readme() would use webshot (or webshot2) to snap a picture of the generated table for use in GitHub documents and would just use the normal HTML for my package's documentation site online.

Right now, I'm saving my flextables as pngs and importing them manually into the README.md file (so my .Rmd and .md files are not equivalent which I'd like to avoid). It's not exactly feasible to keep generating table images every time I change a function :D.

I'll try my best to put a reproducible example of my README.Rmd but it may be tricky since I'm operating in a package environment. Packages needed are dplyr, flextable, and knitr as well as the pipe, %>%.

Example Function

#' Sample Function
#'
#' @param data data
#' @param vars the vars
#'
#' @return a table
#' @export
#'
#' @examples
#' tbl_head(mtcars, c(cyl, gear))
tbl_head <- function(data, vars) {
  
  data_name <- deparse(substitute(data))
  
  data <- head(data) %>% 
    dplyr::select({{ vars }})
  
  tbl <- flextable::flextable(data) %>% 
    flextable::set_caption(paste("Head of Data Table", data_name))
  
  tbl
  
}

Example README.Rmd

---
output: github_document
---

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "80%"
)

Here is how to use this function.

library(temp_pkg)

tbl_head(mtcars, c(cyl, gear))

Any help or discussion is much appreciated!

[jennybc]

Yeah GitHub-flavored markdown is never going to play nicely with your flextables. The "basic markdown" vibe is intentional for README.[R]md since README.md actually goes to CRAN and is displayed on CRAN landing pages. So that markdown needs to remain fairly low-tech.

Most people allow index.html for their pkgdown site to be created from README.md, but there are other options and I think this might apply to you:

The main content of the home page (index.html) is generated from pkgdown/index.md, index.md, or README.md, in that order. Most packages will use README.md because that's also displayed by GitHub and CRAN. Use index.md if you want your package website to look different to your README, and use pkgdown/index.md if you don't want that file to live in your package root directory.

If you use index.Rmd or README.Rmd it's your responsibility to knit the document to create the corresponding .md. pkgdown does not do this for you because it only touches files in the doc/ directory.

https://pkgdown.r-lib.org/reference/build_home.html#home-page

I think this is not a problem we can solve for you in devtools, but I think you can solve it with more work on the pkgdown side.

[ateucher]

Late to the story here, but I have found this works for me if I use webshot, not webshot2. I believe knitr looks first for webshot2, so if you have it installed, you need to uninstall it. And webshot requires phantomjs:

# remove.packages("webshot2") # If it is installed
install.packages("webshot")
webshot::install_phantomjs()
devtools::build_readme()

This successfully renders html output (mapview) to pngs in my README eg here.

Re webshot2, I think there is an issue properly launching chromote in some situations, but I can't find where that is now...

Edit: This doesn't solve the rendering of html in pkgdown, but does automatically create the pngs in the README.md