diff --git a/DESCRIPTION b/DESCRIPTION index 8d4b886..3e41a23 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -3,11 +3,11 @@ 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 Imports: bookdown, knitr (>= 1.12), rmarkdown (>= 1.2), stats, utils, yaml, - BiocManager + whisker, BiocManager Suggests: BiocGenerics, RUnit, htmltools biocViews: Software License: Artistic-2.0 @@ -15,4 +15,4 @@ 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 diff --git a/NAMESPACE b/NAMESPACE index 7e76a67..a7209eb 100644 --- a/NAMESPACE +++ b/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) diff --git a/R/use_vignette.R b/R/use_vignette.R index 467f26c..97a7ecf 100644 --- a/R/use_vignette.R +++ b/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 = "iman.author@some.where", +#' 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" + ) } diff --git a/inst/rmarkdown/templates/package_vignette/README.md b/inst/rmarkdown/templates/package_vignette/README.md new file mode 100644 index 0000000..c304bdf --- /dev/null +++ b/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. diff --git a/inst/rmarkdown/templates/package_vignette/skeleton.Rmd.whisker b/inst/rmarkdown/templates/package_vignette/skeleton.Rmd.whisker new file mode 100644 index 0000000..bbf212c --- /dev/null +++ b/inst/rmarkdown/templates/package_vignette/skeleton.Rmd.whisker @@ -0,0 +1,81 @@ +--- +title: "{{title}}" +author: +{{#authors}} +{{{author}}} +{{/authors}} +{{^authors}} +- name: First Last + email: your@email.address + affiliation: Institutional Affiliation +{{/authors}} +package: {{{package}}} +output: + BiocStyle::{{{output}}}_document +abstract: | + {{abstract}} +vignette: | + %\VignetteIndexEntry{ {{{title}}} } + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + + + +# 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} + + + +## Session info {.unnumbered} + +```{r sessionInfo, echo = FALSE} +sessionInfo() +``` diff --git a/inst/rmarkdown/templates/package_vignette/skeleton/skeleton.Rmd b/inst/rmarkdown/templates/package_vignette/skeleton/skeleton.Rmd new file mode 100644 index 0000000..0eae374 --- /dev/null +++ b/inst/rmarkdown/templates/package_vignette/skeleton/skeleton.Rmd @@ -0,0 +1,76 @@ +--- +title: "Introduction to MyPackage" +author: +- name: Given Family + email: your@email.address + affiliation: Institutional Affiliation +package: MyPackage +output: + BiocStyle::html_document +abstract: | + Describe your vignette with a paragraph-length summary. +vignette: | + %\VignetteIndexEntry{ Introduction to MyPackage } + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + + + +# Installation + +Install the _MyPackage_ package with + +```{r, eval = FALSE} +if (!requireNamespace("BiocManager", quietly = TRUE)) + install.packages("BiocManager", repos = "https://cran.r-project.org") +BiocManager::install("MyPackage") +``` + +Once installed, load the package with + +```{r, message = FALSE} +library(MyPackage) +``` + +# 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 'MyPackage', 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/MyPackage +``` + +Use the [bug report url][] to report bugs in _MyPackage_; remember +to reduce your bug report to a simple reproducible example. + +[support site]: https://support.bioconductor.org +[bug report url]: https://support.bioconductor.org + +# Appendix {.unnumbered} + +## Acknowldegements {.unnumbered} + + + +## Session info {.unnumbered} + +```{r sessionInfo, echo = FALSE} +sessionInfo() +``` diff --git a/inst/rmarkdown/templates/package_vignette/template.yaml b/inst/rmarkdown/templates/package_vignette/template.yaml new file mode 100644 index 0000000..c50e704 --- /dev/null +++ b/inst/rmarkdown/templates/package_vignette/template.yaml @@ -0,0 +1,4 @@ +name: Bioconductor Package Vignette +description: > + Template for Bioconductor package vignettes. +create_dir: false diff --git a/man/html_document.Rd b/man/html_document.Rd index 51b18cb..f845850 100644 --- a/man/html_document.Rd +++ b/man/html_document.Rd @@ -4,9 +4,17 @@ \alias{html_document} \title{Use Bioconductor style to format R Markdown HTML output} \usage{ -html_document(toc = TRUE, number_sections = TRUE, fig_width = NA, - fig_height = NA, self_contained = TRUE, css = NULL, - pandoc_args = NULL, ..., titlecaps = TRUE) +html_document( + toc = TRUE, + number_sections = TRUE, + fig_width = NA, + fig_height = NA, + self_contained = TRUE, + css = NULL, + pandoc_args = NULL, + ..., + titlecaps = TRUE +) } \arguments{ \item{toc}{logical(1), \code{TRUE} to include a table of contents in the diff --git a/man/latex.Rd b/man/latex.Rd index 9f890ee..81cf18b 100644 --- a/man/latex.Rd +++ b/man/latex.Rd @@ -4,8 +4,15 @@ \alias{latex} \title{Use Bioconductor style to format LaTeX vignettes} \usage{ -latex(..., width, titlecaps = TRUE, short.fignames = FALSE, fig.path, - use.unsrturl = TRUE, relative.path = FALSE) +latex( + ..., + width, + titlecaps = TRUE, + short.fignames = FALSE, + fig.path, + use.unsrturl = TRUE, + relative.path = FALSE +) } \arguments{ \item{\dots}{Additional arguments, passed to \code{\link{options}}.} diff --git a/man/pdf_document.Rd b/man/pdf_document.Rd index bf91167..8476ddd 100644 --- a/man/pdf_document.Rd +++ b/man/pdf_document.Rd @@ -4,9 +4,18 @@ \alias{pdf_document} \title{Use Bioconductor style to format R Markdown PDF output} \usage{ -pdf_document(toc = TRUE, number_sections = TRUE, fig_width = NA, - fig_height = NA, includes = NULL, ..., titlecaps = TRUE, - toc_newpage = FALSE, use_unsrturl = TRUE, relative_path = FALSE) +pdf_document( + toc = TRUE, + number_sections = TRUE, + fig_width = NA, + fig_height = NA, + includes = NULL, + ..., + titlecaps = TRUE, + toc_newpage = FALSE, + use_unsrturl = TRUE, + relative_path = FALSE +) } \arguments{ \item{toc}{logical(1), \code{TRUE} to include a table of contents in the diff --git a/man/use_vignette.Rd b/man/use_vignette.Rd index a8ee5c5..73176d1 100644 --- a/man/use_vignette.Rd +++ b/man/use_vignette.Rd @@ -1,24 +1,77 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/use_vignette.R -\name{use_vignette_html} +\name{use_vignette} +\alias{use_vignette} \alias{use_vignette_html} \alias{use_vignette_pdf} +\alias{use_package_vignette_html} +\alias{use_package_vignette_pdf} \title{Create 'Rmd' vignette templates for HTML or PDF output} \usage{ use_vignette_html(destination = tempfile(fileext = ".Rmd")) use_vignette_pdf(destination = tempfile(fileext = ".Rmd")) + +use_package_vignette_html( + 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" +) + +use_package_vignette_pdf( + 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" +) } \arguments{ -\item{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.} +\item{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.} + +\item{package}{character(1) package name.} + +\item{title}{character(1) vignette title.} + +\item{abstract}{character(1) paragraph-length summary of the vignette.} + +\item{authors}{person() vignette authors. Use `person(comment = +...)` to include author affiliation (see examples).} + +\item{bug_report_url}{character(1) url for bug reports (e.g., +`"https://github.com/Bioconductor/BiocStyle/issues"`)} } \description{ -Create 'Rmd' vignette templates for HTML or PDF output +`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. + +`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. } \examples{ -use_vignette_html() - +vignette <- use_package_vignette_html( + authors = c( + person( + "Iman", "Author", + email = "iman.author@some.where", + comment = c(affiliation = "Prestigious Institution") + ), + person("Iman", "Other") + ) +) +vignette +cat(readLines(vignette), "\n") }