Merge pull request #61 from FredHutch/release-v0.3.0

Release v0.3.0

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: VISCtemplates
 Title: Tools for writing reproducible reports at VISC
-Version: 0.2.0
+Version: 0.3.0
 Authors@R: 
     person(given = "Jimmy",
            family = "Fulp",
@@ -19,14 +19,16 @@ License: GPL-3 + file LICENSE
 Depends: R (>= 3.0)
 Imports:
     bookdown,
+    here,
     rmarkdown,
     stringr,
     usethis
 Encoding: UTF-8
 LazyData: true
 URL: https://github.com/FredHutch/VISCtemplates
 BugReports: https://github.com/FredHutch/VISCtemplates/issues
-RoxygenNote: 7.1.0
+RoxygenNote: 7.1.1
+Roxygen: list(markdown = TRUE)
 Suggests: 
     knitr,
     testthat (>= 2.1.0)

NEWS.md

@@ -1,3 +1,16 @@
+# VISCtemplates 0.3.0
+
+* New "empty" report template without the boilerplate PT report text.
+    + Go to `File > New File > Rmarkdown... > From Template` and select the "Empty Report" template.
+    + Or use `template = "visc_empty"` argument in `rmarkdown::draft()`.
+    + See the updated vignette for more info.
+* Changes to `bibliography.bib` file.
+    + Shortened file contains only citations used in VISC reports.
+    + A project-level `bibliography.bib` file is written to the `docs/` directory. Previously there was one file generated for each report.
+* New Github PR text links to the documentation for writing and code review.
+* Bug fixes:
+    + Footnote hyperlinks fixed: `Footnote text (^[MY_FOOTNOTE])`.
+
 # VISCtemplates 0.2.0
 
 * Changes to VISC Report (PDF & Word Output) template.

R/report_template.R

@@ -27,30 +27,49 @@ install_load_cran_packages <- function(packages) {
 #' @export
 #'
 #' @examples
-#' \dontrun{check_pandoc_version}
+#' \dontrun{check_pandoc_version()}
 #'
 check_pandoc_version <- function() {
   if (numeric_version(rmarkdown::pandoc_version()) < numeric_version('2.0'))
     stop('pandoc must be at least version "2.0')
 }
 
-#' Cross-reference a figure or table
+#' Cross-reference a figure, table, or section
 #'
 #' @param ref character string with the reference type and chunk label
+#' @param section_name character string with the section name to
+#' display for Word output (default is NA)
+#'
+#' @return inserts a link to a table, figure, or section in a PDF or Word report
+#'
+#' @details \code{section_name} only used for Word output (pandoc).
+#' For Word output, if \code{section_name} is not NA a section reference
+#' is created, otherwise a figure or table reference is created.
 #'
-#' @return inserts a link to a table or figure in a PDF or Word report
 #' @export
 #'
 #' @examples
 #'
 #' \dontrun{insert_ref("tab:my-results")}
 #' \dontrun{insert_ref("fig:box-plots")}
-insert_ref <- function(ref) {
-  ifelse(knitr::opts_knit$get('rmarkdown.pandoc.to') == 'latex',
-         paste0('\\ref{', ref, '}'),
-         paste0('\\@ref(', ref, ')'))
+#' \dontrun{insert_ref("stats-methods")}
+#' \dontrun{insert_ref("stats-methods", "Stats Methods")}
+insert_ref <- function(ref, section_name = NA) {
+  output_type <- knitr::opts_knit$get('rmarkdown.pandoc.to')
+  if (is.null(output_type))
+    return(NULL)
+
+  if (output_type == 'latex') {
+    paste0('\\ref{', ref, '}')
+  } else {
+    if (is.na(section_name))
+      paste0('\\@ref(', ref, ')')
+    else
+      paste0('[', section_name, '](#', ref, ')')
+  }
 }
 
+
 #' Insert a page break
 #'
 #' Use this function in an R Markdown document to insert a page break when you

R/template.R

@@ -21,7 +21,8 @@ use_visc_readme <- function(study_name, save_as = "README.Rmd") {
 #' Create a VISC docs directory with template files
 #'
 #' Creates the docs/ directory and presentations/ directory with templates
-#' for the project background, objectives, group colors, and study schema.
+#' for the project background, objectives, group colors, study schema, and
+#' project-level bib file.
 #'
 #' @param study_name name of study in VDCNNN format
 #'
@@ -47,6 +48,9 @@ use_visc_docs <- function(study_name) {
 
   # study schema template
   use_study_schema(study_name)
+
+  # project-level bib file
+  use_bib(study_name)
 }
 
 
@@ -86,14 +90,23 @@ use_study_schema <- function(study_name) {
   )
 }
 
+use_bib <- function(study_name) {
+  usethis::use_template(
+    template = "bibliography.bib",
+    save_as = "docs/bibliography.bib",
+    data = list(study_name = study_name),
+    package = "VISCtemplates"
+  )
+}
+
 
 #' Convert to a VISC Report PDF/LaTeX document
 #'
 #' Runs the VISC Report for PDF output based on the template.tex file.
 #'
 #' @param latex_engine latex engine to use
 #' @param keep_tex keep the .tex file
-#' @param ... other options to pass to \code{rmarkdown::pdf_document()}
+#' @param ... other options to pass to \code{bookdown::pdf_document2()}
 #'
 #' @details
 #'
@@ -110,11 +123,24 @@ visc_pdf_document <- function(latex_engine = "pdflatex",
   logo_path_fh <- find_resource("visc_report", "FredHutch_logo.png")
   logo_path_visc <- find_resource("visc_report", "VISC_logo.jpg")
 
-  rmarkdown::pdf_document(
+  # If no project-level bib file creating report specific bib
+  if (!file.exists(here::here('docs', 'bibliography.bib'))) {
+    file.copy(from = system.file("templates", 'bibliography.bib',
+                                 package = "VISCtemplates"),
+            to = "bibliography.bib",
+            overwrite = FALSE)
+   }
+
+  file.copy(from = find_resource("visc_report", "README_PT_Report.md"),
+            to = "README.md",
+            overwrite = FALSE)
+
+  bookdown::pdf_document2(
     template = template,
     keep_tex = keep_tex,
     fig_caption = TRUE,
     latex_engine = latex_engine,
+    bib_engine = 'biber',
     pandoc_args = c(
       "-V", paste0("logo_path_scharp=", logo_path_scharp),
       "-V", paste0("logo_path_fh=", logo_path_fh),
@@ -146,11 +172,22 @@ visc_word_document <- function(toc = TRUE,
 
   word_style_path <- find_resource("visc_report", "word-styles-reference.docx")
 
+  # If no project-level bib file creating report specific bib
+  if (!file.exists(here::here('docs', 'bibliography.bib'))) {
+    file.copy(from = system.file("templates", 'bibliography.bib',
+                                 package = "VISCtemplates"),
+              to = "bibliography.bib",
+              overwrite = FALSE)
+  }
+
+  file.copy(from = find_resource("visc_report", "README_PT_Report.md"),
+            to = "README.md",
+            overwrite = FALSE)
+
   bookdown::word_document2(
     toc = toc,
     fig_caption = fig_caption,
     keep_md = keep_md,
     reference_docx = word_style_path,
     ...)
 }
-

R/use_visc_gitignore.R

@@ -16,6 +16,12 @@ use_visc_gitignore <- function(directory = ".") {
   # files that we frequently don't want to track
   usethis::use_git_ignore(
     ignores = c(
+      # Default RStudio entries
+      ".Rproj.user",
+      ".Rhistory",
+      ".RData",
+      ".Ruserdata",
+      # VISCtemplates specific entries
       "README.html",
       "~$*.doc*",
       "~$*.xls*",
@@ -30,7 +36,8 @@ use_visc_gitignore <- function(directory = ".") {
       "Thumbs.db",
       # files from Latex
       "*.log",
-      "**/figure-latex/*.pdf"
+      "**/figure-latex/*.pdf",
+      "**/figure-docx/*.pdf"
     ),
     directory = directory
   )

R/use_visc_pr_template.R

@@ -8,8 +8,8 @@ use_visc_pr_template <- function() {
   usethis::use_directory(".github")
 
   usethis::use_template(
-    template = "pull_request_template.txt",
-    save_as = ".github/pull_request_template.txt",
+    template = "pull_request_template.md",
+    save_as = ".github/pull_request_template.md",
     data = list(),
     package = "VISCtemplates"
   )

README.Rmd

@@ -34,8 +34,9 @@ The package is available on the Fred Hutch organization GitHub page.
 ```{r eval=FALSE}
 remotes::install_github("FredHutch/VISCtemplates")
 
-# to access the vignette, use devtools:
-devtools::install_github("FredHutch/VISCtemplates", build_vignettes = TRUE)
+# Use the build_vignettes parameter to access the vignette:
+remotes::install_github("FredHutch/VISCtemplates", build_vignettes = TRUE)
+vignette("using_pdf_and_word_template")
 ```
 
 ## Requirements
@@ -63,7 +64,7 @@ This function will produce the following structure and templates:
 ```
 [VDCnnn]Analysis
 |- .github/
-|  +- pull_request_template.txt   # template for GitHub PRs
+|  +- pull_request_template.md   # template for GitHub PRs
 |
 |- .gitignore                     # File types that VISC ignores
 |- .Rbuildignore                  # Auto-generated for package development (ignore)
@@ -105,7 +106,11 @@ Note that you must have a [personal access token (PAT)](https://happygitwithr.co
 
 You still need to set the permissions to the project to vidd-visc:
 
-Settings → Manage access → Invite teams or people (button) → vidd-visc (shows up as FredHutch/vidd-visc)
+* Settings → Manage access → Invite teams or people (button) → vidd-visc (shows up as FredHutch/vidd-visc)
+
+Set up branch protections:
+
+* Settings → Branches → Branch protection rule → Branch name pattern: master (or some other branch you want to protect) → Require pull request reviews before merging. 
 
 ### Step Three: Documentation
 

README.md

@@ -25,8 +25,9 @@ The package is available on the Fred Hutch organization GitHub page.
 ``` r
 remotes::install_github("FredHutch/VISCtemplates")
 
-# to access the vignette, use devtools:
-devtools::install_github("FredHutch/VISCtemplates", build_vignettes = TRUE)
+# Use the build_vignettes parameter to access the vignette:
+remotes::install_github("FredHutch/VISCtemplates", build_vignettes = TRUE)
+vignette("using_pdf_and_word_template")
 ```
 
 ## Requirements
@@ -58,7 +59,7 @@ This function will produce the following structure and templates:
 
     [VDCnnn]Analysis
     |- .github/
-    |  +- pull_request_template.txt   # template for GitHub PRs
+    |  +- pull_request_template.md   # template for GitHub PRs
     |
     |- .gitignore                     # File types that VISC ignores
     |- .Rbuildignore                  # Auto-generated for package development (ignore)
@@ -101,8 +102,14 @@ Note that you must have a [personal access token
 
 You still need to set the permissions to the project to vidd-visc:
 
-Settings → Manage access → Invite teams or people (button) → vidd-visc
-(shows up as FredHutch/vidd-visc)
+  - Settings → Manage access → Invite teams or people (button) →
+    vidd-visc (shows up as FredHutch/vidd-visc)
+
+Set up branch protections:
+
+  - Settings → Branches → Branch protection rule → Branch name pattern:
+    master (or some other branch you want to protect) → Require pull
+    request reviews before merging.
 
 ### Step Three: Documentation