7

I am trying to compile a package vignette such that an .md file remains in the vignette folder so that it is still visible on github. I am using devtools for all of this. I have looked at this approach and will outline it below:

I have auto-generated a vignette template use devtools::use_vignette(). Then I have modified the .Rmd file to look like this (truncated template version):

---
  title: "package"
author: "author"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
  toc: true
  keep_md: true
vignette: >
  %\VignetteIndexEntry{Vignette Title}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---

  Vignettes are long form documentation commonly included in packages. Because they are part of the distribution of the package, they need to be as compact as possible. The `html_vignette` output type provides a custom style sheet (and tweaks some options) to ensure that the resulting html is as small as possible. The `html_vignette` format:

  - Never uses retina figures
- Has a smaller default figure size
- Uses a custom CSS stylesheet instead of the default Twitter Bootstrap style

## Vignette Info

Note the various macros within the `vignette` section of the metadata block above. These are required in order to instruct R how to build the vignette. Note that you should change the `title` field and the `\VignetteIndexEntry` to match the title of your vignette.

So the .yaml is modified but when I compile using devtools::build_vignettes() it does not seem to leave a .md file in the vignettes directory. No error message and the vignette builds fine so this is a little confusing.

So to summarize the question, do anyone know how to compile a vignette using devtools::build_vignette such that the basic markdown file is kept in the vignettes directory?

boshek
  • 4,100
  • 1
  • 31
  • 55

1 Answers1

11

If you are open to functions other than build_vignette(), then it is quite easy because at the end of the day, everything is just a wrapper for the external pandoc binary.

/tmp/vig> ls -l     ## start with nothing but Rmd
total 4
-rw-r--r-- 1 user grp 1015 Aug 10 14:21 soVig.Rmd
/tmp/vig> 
/tmp/vig> Rscript -e 'rmarkdown::render("soVig.Rmd", clean=FALSE)'


processing file: soVig.Rmd
  |.................................................................| 100%
   inline R code fragments


output file: soVig.knit.md

/usr/bin/pandoc +RTS -K512m -RTS soVig.utf8.md --to html --from markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash --output soVig.html --smart --email-obfuscation none --self-contained --standalone --section-divs --template /usr/local/lib/R/site-library/rmarkdown/rmd/h/default.html --highlight-style pygments --css /usr/local/lib/R/site-library/rmarkdown/rmarkdown/templates/html_vignette/resources/vignette.css --mathjax --variable 'mathjax-url:https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML' 

Output created: soVig.html
/tmp/vig> ls -l soVig.*
-rw-r--r-- 1 user grp 7066 Aug 10 14:24 soVig.html
-rw-r--r-- 1 user grp 1011 Aug 10 14:24 soVig.knit.md
-rw-r--r-- 1 user grp 1015 Aug 10 14:21 soVig.Rmd
-rw-r--r-- 1 user grp 1011 Aug 10 14:24 soVig.utf8.md
/tmp/vig>

so by simply telling render() to not clean we get to keep the markdown source.

Dirk Eddelbuettel
  • 360,940
  • 56
  • 644
  • 725
  • 1
    I'd sorted of like to stay in `devtools`. Ultimately this is for a package that is currently only hosted in github (but will CRAN intended) so I would add the `.md` to`.RBuildIgnore` but keep it present in the repo so that I can point to it as long form documentation. – boshek Aug 10 '17 at 20:39
  • 2
    Up to you. Last I checked, I wasn't yet outlawed to combine several different packages and base R. – Dirk Eddelbuettel Aug 10 '17 at 20:41
  • Sorry, I should have been specific. I just meant that staying in `devtools` meant that hopefully I wasn't left will all the other cruft from `render` (.knit.md. utf8.md, ,html) – boshek Aug 10 '17 at 20:42
  • 2
    Yes, sure, one call each to `file.rename()` and `file.remove()` is clearly too difficult. – Dirk Eddelbuettel Aug 10 '17 at 20:46
  • 1
    Actually I had not thought of that. Good idea. So something like this? `render_keep_md = function(vignette_name){ rmarkdown::render(paste0("./vignettes/",vignette_name, ".Rmd"), clean=FALSE) files_to_remove = paste0("./vignettes/",vignette_name,c(".html",".knit.md",".utf8.md")) lapply(files_to_remove, file.remove) }` – boshek Aug 10 '17 at 21:02
  • Yep. You need to keep one of the two `.md` files though, and maybe rename it. – Dirk Eddelbuettel Aug 10 '17 at 21:04
  • Sorry Dirk - why do I need to keep it? A `.md` is already produced. – boshek Aug 10 '17 at 21:06
  • 1
    In the `ls -l` out I show above we have one input, one final output, and by setting `clean=FALSE` to interim files. If you remove both you are undoing the work. What am I (or you) missing here? – Dirk Eddelbuettel Aug 10 '17 at 21:10
  • Nope I understand now. Learned something today. Thanks! – boshek Aug 10 '17 at 21:18
  • My pleasure. If the answer suits, feel free to grace it with an upvote. – Dirk Eddelbuettel Aug 10 '17 at 21:34
  • It does - I am going to see if someone more directly answer the exact question before accepting your answer. – boshek Aug 10 '17 at 21:38
  • I think Dirk's got the solution here. I had a similar problem, with the caveat that I desired outputs in both .html and .pdf as well. After wasting much time on the `build_vignette()` function, the `rmarkdown::render("vignettes/soVig.Rmd", output_format = "all", clean=FALSE)` ultimately did what I needed. Of all approaches I considered, the `render()` function provided the most control over the process. – Justin Aug 13 '17 at 22:26
  • One suggestion is to create a separate `.R` file for using `render()` along with the functions to remove and rename files. Then `.RBuildIgnore` that file. The script will come in handy for future packages with similar vignette requirements. – Justin Aug 13 '17 at 22:30
  • Yes, I keep similar `buildVignettes.r` helpers (shebang'ed for either littler or Rscript) in some vignettes/ directories. A little hard to generalize, but the key is in fact the use of `rmarkdown::render()`. – Dirk Eddelbuettel Aug 13 '17 at 22:33