Enhance use_vignette_*()

DESCRIPTION

@@ -3,16 +3,16 @@ Title: Standard styles for vignettes and other Bioconductor documents
 Description: Provides standard formatting styles for Bioconductor PDF
     and HTML documents. Package vignettes illustrate use and
     functionality.
-Version: 2.17.0
+Version: 2.17.0-1
 Author: Andrzej Oleś, Martin Morgan, Wolfgang Huber
 Maintainer: Bioconductor Package Maintainer <[email protected]>
 Imports: bookdown, knitr (>= 1.12), rmarkdown (>= 1.2), stats, utils, yaml,
-    BiocManager
+    whisker, BiocManager
 Suggests: BiocGenerics, RUnit, htmltools
 biocViews: Software
 License: Artistic-2.0
 VignetteBuilder: knitr
 Encoding: UTF-8
 URL: https://github.com/Bioconductor/BiocStyle
 BugReports: https://github.com/Bioconductor/BiocStyle/issues
-RoxygenNote: 6.1.0
+RoxygenNote: 7.1.0

NAMESPACE

@@ -14,6 +14,8 @@ export(md_document)
 export(output)
 export(pdf_document)
 export(pkg_ver)
+export(use_package_vignette_html)
+export(use_package_vignette_pdf)
 export(use_vignette_html)
 export(use_vignette_pdf)
 importFrom(BiocManager,version)
@@ -35,4 +37,6 @@ importFrom(rmarkdown,pandoc_available)
 importFrom(rmarkdown,pandoc_version)
 importFrom(stats,setNames)
 importFrom(utils,packageVersion)
+importFrom(utils,person)
+importFrom(whisker,whisker.render)
 importFrom(yaml,yaml.load)

R/use_vignette.R

@@ -1,44 +1,178 @@
+#' @rdname use_vignette
+#'
+#' @title Create 'Rmd' vignette templates for HTML or PDF output
+#'
+#' @name use_vignette
+#'
+#' @param destination character(1) file path to destination, usually
+#'     inside the `"vignettes"` directory of `package`. The directory
+#'     of the destination must already exist, and the file must
+#'     not. The default creates a file in the temporary directory, and
+#'     so is removed when the R session ends.
+#'
+#' @param package character(1) package name.
+#'
+#' @param title character(1) vignette title.
+#'
+#' @param abstract character(1) paragraph-length summary of the vignette.
+#'
+#' @param authors person() vignette authors. Use `person(comment =
+#'     ...)` to include author affiliation (see examples).
+#'
+#' @param bug_report_url character(1) url for bug reports (e.g.,
+#'     `"https://github.com/Bioconductor/BiocStyle/issues"`)
+#'
+#' @examples
+#' vignette <- use_package_vignette_html(
+#'     authors = c(
+#'         person(
+#'             "Iman", "Author",
+#'             email = "[email protected]",
+#'             comment = c(affiliation = "Prestigious Institution")
+#'         ),
+#'         person("Iman", "Other")
+#'     )
+#' )
+#' vignette
+#' cat(readLines(vignette), "\n")
+NULL
+
 #' @importFrom rmarkdown draft
-.vignette_template <-
-    function(destination, mode = c("html", "pdf"))
+.vignette_render <-
+    function(destination, output = c("html", "pdf"))
+{
+     stopifnot(
+         is.character(destination), length(destination) == 1L,
+         !is.na(destination),
+         !file.exists(destination), file.exists(dirname(destination))
+     )
+     output <- match.arg(output)
+
+     doc <- paste(output, "document", sep = "_")
+     draft(destination, template = doc, package = "BiocStyle", edit = FALSE)
+     destination
+}
+
+#' @rdname use_vignette
+#'
+#' @description `use_vignette_html()` and `use_vignette_pdf()` create
+#'     markdown vignettte templates for general use, in html or pdf
+#'     formats. The template outlines markdown syntax and unique
+#'     features enabled by BiocStyle.
+#'
+#' @export
+use_vignette_html <-
+    function(destination = tempfile(fileext = ".Rmd"))
+{
+    .vignette_render(destination, "html")
+}
+
+#' @rdname use_vignette
+#'
+#' @export
+use_vignette_pdf <-
+    function(destination = tempfile(fileext = ".Rmd"))
+{
+    .vignette_render(destination, "pdf")
+}
+
+#' @importFrom utils person
+#'
+#' @importFrom whisker whisker.render
+.package_vignette_render <-
+    function(
+        destination, package, title, abstract, authors, bug_report_url,
+        output = c("html", "pdf")
+    )
 {
     stopifnot(
-        is.character(destination), length(destination) == 1L, !is.na(destination),
-        !file.exists(destination), file.exists(dirname(destination))
+        length(destination) == 1L,
+        dir.exists(dirname(destination)), !file.exists(destination),
+        is.character(package), length(package) == 1L,
+        is.character(title), length(title) == 1L,
+        is.character(abstract), length(abstract) == 1L,
+        inherits(authors, "person"),
+        is.character(bug_report_url), length(bug_report_url) == 1L
+    )
+    output <- match.arg(output)
+
+    ## processing to list of authors, each author markdown formatted
+    authors_data <- format(
+        authors,
+        fields = c("given", "family", "email", "comment"),
+        braces = list(
+            given = c("- name: ", ""),
+            email = c("\n  email: ", ""),
+            comment = c("\n  affilation: ", "")
+        )
+    )
+    authors <- lapply(authors_data, function(author) {
+        author <- gsub("[[:space:]]+\n", "\n", author) # trailing whitespace
+        list(author = author)
+    })
+
+    ## data for whisker variable substitution
+    data <- list(
+        package = package,
+        title = title,
+        abstract = abstract,
+        authors = authors,
+        bug_report_url = bug_report_url,
+        output = output
     )
-    mode <- match.arg(mode)
 
-    doc <- paste(mode, "document", sep = "_")
-    rmarkdown::draft(
-        destination, template = doc, package = "BiocStyle", edit = FALSE
+    ## draft via rmarkdown
+    whisker <- system.file(
+        package = "BiocStyle", "rmarkdown", "templates", "package_vignette",
+        "skeleton.Rmd.whisker"
     )
-    destination
+
+    ## inject values via whisker
+    rendered <- whisker.render(readLines(whisker), data)
+    writeLines(rendered, destination)
+
+    invisible(destination)
 }
 
-#' @title Create 'Rmd' vignette templates for HTML or PDF output
-#'
 #' @rdname use_vignette
-#' 
-#' @param destination character(1) file path to destination. The 
-#'     directory of the destination must already exist, and the file 
-#'     must not. The default creates a file in the temporary 
-#'     directory, and so is removed when the R session ends.
-#' 
-#' @examples
-#' use_vignette_html()
+#'
+#' @description `use_package_vignette_html()` and
+#'     `use_package_vignette_pdf()` create vignette templates suitable
+#'     for inclusion in Bioconductor packages. The templates contain
+#'     package installation instructions, suggest overall structure,
+#'     and provide locations to seek support and create bug reports.
 #'
 #' @export
-use_vignette_html <- 
-    function(destination = tempfile(fileext = ".Rmd")) 
+use_package_vignette_html <-
+    function(
+        destination = tempfile(fileext = ".Rmd"),
+        package = "MyPackage",
+        title = paste("Introduction to", package),
+        abstract = "Describe your vignette with a paragraph-length summary.",
+        authors = person(),
+        bug_report_url = "https://support.bioconductor.org"
+    )
 {
-    .vignette_template(destination, "html")
+    .package_vignette_render(
+        destination, package, title, abstract, authors, bug_report_url, "html"
+    )
 }
 
+
 #' @rdname use_vignette
 #'
 #' @export
-use_vignette_pdf <- 
-    function(destination = tempfile(fileext = ".Rmd")) 
+use_package_vignette_pdf <-
+    function(
+        destination = tempfile(fileext = ".Rmd"),
+        package = "MyPackage",
+        title = paste("Introduction to", package),
+        abstract = "Describe your vignette with a paragraph-length summary.",
+        authors = person(),
+        bug_report_url = "https://support.bioconductor.org"
+    )
 {
-    .vignette_template(destination, "pdf")
+    .package_vignette_render(
+        destination, package, title, abstract, authors, bug_report_url, "pdf"
+    )
 }

inst/rmarkdown/templates/package_vignette/README.md

@@ -0,0 +1,18 @@
+To update the vignette
+
+1. Modify `skeleton.Rmd.whisker`
+
+2. Use `BiocStyle::use_vignette_html()` to update `skeleton/skeleton.Rmd`
+
+    ```{r}
+    devtools::load_all() # in BiocStyle source directory
+    destination <- file.path(
+        "inst", "rmarkdown", "templates", "package_vignette", "skeleton",
+        "skeleton.Rmd"
+    )
+    BiocStyle::use_vignette_html(destination)
+    ```
+
+These steps keep the vignette produced by `use_vignette_html()` in
+sync with selecting 'Bioconductor package vignette' from the RStudio
+`File -> New File -> R Markdown -> From Template` menu.

inst/rmarkdown/templates/package_vignette/skeleton.Rmd.whisker

@@ -0,0 +1,81 @@
+---
+title: "{{title}}"
+author:
+{{#authors}}
+{{{author}}}
+{{/authors}}
+{{^authors}}
+- name: First Last
+  email: [email protected]
+  affiliation: Institutional Affiliation
+{{/authors}}
+package: {{{package}}}
+output:
+  BiocStyle::{{{output}}}_document
+abstract: |
+  {{abstract}}
+vignette: |
+  %\VignetteIndexEntry{ {{{title}}} }
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+<!--
+To enable the _Bioconductor_ style in your R Markdown vignette you
+need to include the following in the `DESCRIPTION` file:
+
+    VignetteBuilder: knitr
+    Suggests: BiocStyle, knitr
+-->
+
+# Installation
+
+Install the _{{package}}_ package with
+
+```{r, eval = FALSE}
+if (!requireNamespace("BiocManager", quietly = TRUE))
+    install.packages("BiocManager", repos = "https://cran.r-project.org")
+BiocManager::install("{{{package}}}")
+```
+
+Once installed, load the package with
+
+```{r, message = FALSE}
+library({{{package}}})
+```
+
+# Quick start
+
+# Common work flows
+
+# Interoperability with other _Bioconductor_ packages
+
+# Support, bug reports, and source code availability
+
+Please ask for help about using this package on the [support
+site][]. Remember to tag your question with '{{{package}}}', so that
+the maintainer is notified.
+
+Retrieve the source code for this package from it's cannonical location
+
+```
+git clone https://git.bioconductor.org/packages/{{{package}}}
+```
+
+Use the [bug report url][] to report bugs in _{{{package}}}_; remember
+to reduce your bug report to a simple reproducible example.
+
+[support site]: https://support.bioconductor.org
+[bug report url]: {{{bug_report_url}}}
+
+# Appendix {.unnumbered}
+
+## Acknowldegements {.unnumbered}
+
+<!-- acknowledge funding and other sources of support here -->
+
+## Session info {.unnumbered}
+
+```{r sessionInfo, echo = FALSE}
+sessionInfo()
+```