pre-rendered Shiny Rmd documents should have a cache invalidation mechanism

[bborgesr]

This is an issue that has come up in discussion before (in fact the title is verbatim stolen from @yihui 's comment in https://github.com/rstudio/rmarkdown/issues/1213#issuecomment-349420987). I have now bumped into it again because, with the latest rmarkdown version now on CRAN, I was testing learnr (using the tutorials in the repo's examples directory) and hitting the same obscure error:

This turned out to be another "highlight.js 1.1" issue since I still had the .html files and other artifacts from previous rendered versions of the shiny pre-rendered Rmd file. I think that the reason that https://github.com/rstudio/learnr/commit/6eb75a031a0a6977e4731697c098c66b208c72de was not enough is because there's also a call to normalizePath(directoryPath, mustWork=TRUE) in shiny that tries to fetch the highlight.js dependency. (From the shiny side, we could wrap this call in a tryCatch and provide a better error message than the result above.)

In any case, like in #1213, the issue is fixed by deleting the html file and re-rendering from scratch. However, this revives the problem of missing a cache invalidation mechanism and is, in the end, to be expected, as @jjallaire put it (https://github.com/rstudio/rmarkdown/issues/1213#issuecomment-349421582):

Yes, Winston that all stems for the cache invalidation.

@yihui You are absolutely right that they need a cache invalidation mechanism or we will continue to see this sort of thing periodically.

Also, in that same issue, @jcheng5 sketched out a possible solution: see https://github.com/rstudio/rmarkdown/issues/1213#issuecomment-350376918.

[wch]

Just a little context: If someone has a pre-rendered html file generated from a .Rmd, and then they upgrade packages that have changes html dependencies, they'll see cryptic errors like Error in normalizePath: path[1]="": No such file or directory. There's no clue to the user that the problem is that the cached html file is out of date, and so they're likely to get the impression that rmarkdown or learnr is flaky.

[yihui]

It was probably due to c5fa1ee84115905b84fad42d2152f05ffc34a085. I'm not sure. But I guess once the html file is regenerated, things will become stable again from rmarkdown 1.9.

For the highlight.js dependency, I have monkey-patched it on rmarkdown's side in d3331691947add59b20c65459e1f3a0b3f15173e. In theory, shiny could do the same thing, but it is probably not worth it, since monkey-patching is not a very good idea, and the fundamental fix should be a cache invalidation mechanism (regenerate the html file when necessary -- perhaps after the rmarkdown version has changed?).

[bborgesr]

@yihui, do you have any rough estimate when the cache invalidation mechanism would be in place? Winston provided much needed context that I'd left out: our major worry is not about having to delete our own .html files - once you realize the fix, it's incredibly simple. However, since it's so cryptic, we're just trying to get ahead of users getting the impression that learnr/shiny prerendered re-renderings after upgrades are bound to be flaky and cryptic...

[jcheng5]

@rich-iannone I think this is one worth getting your head around, feel free to ping @wch or myself for the full context.

[rich-iannone]

@jcheng5 I'll prioritize this one (and get in touch with one of you soon to get a better understanding of it).