v1 (#44)

* phs_report_docx rmd type

* re-add compile_report function

Co-authored-by: Alan Yeung <[email protected]>

DESCRIPTION

@@ -4,7 +4,7 @@ Authors@R: c(
     person("Alan", "Yeung", email = "[email protected]", role = c("aut", "cre"), comment = c(ORCID = "0000-0001-5226-3695")),
     person("Anna", "Price", email = "[email protected]", role = "aut")
     )
-Version: 0.9.6
+Version: 1.0.0
 Description: Templates for Public Health Scotland.
 Depends: R (>= 3.2.0)
 License: GPL (>= 2)
@@ -25,6 +25,6 @@ Suggests:
     gdtools
 Imports: 
     magrittr,
-    rmarkdown,
+    rmarkdown (>= 2.12),
     officer,
     renv

NAMESPACE

@@ -3,5 +3,6 @@
 export("%>%")
 export(compile_report)
 export(new_script)
+export(phs_report_docx)
 export(phsproject)
 importFrom(magrittr,"%>%")

NEWS.md

@@ -1,3 +1,9 @@
+# phstemplate 1.0.0
+
+* Added the phs_report_docx RMarkdown document type.
+* Updated the PHS official and national stats report templates to use the phs_report_docx RMarkdown document type.
+* Removed the ISD national stats summary and report templates.
+
 # phstemplates 0.9.6
 
 * Added PHS official and national stats summary and report documents for 2022.

R/phs_report_docx.R

@@ -0,0 +1,152 @@
+#' Convert to a PHS report in MS Word document format
+#'
+#' Format for converting from R Markdown to a PHS report in MS Word document format.
+#' This is an extension of the \code{word_document} format that adds post-processing
+#' to include the front cover and table of contents for the report.
+#'
+#' See the \href{https://bookdown.org/yihui/rmarkdown/word-document.html}{online
+#' documentation} for additional details on using the \code{word_document} format.
+#'
+#' R Markdown documents can have optional metadata that is used to generate a
+#' document header that includes the title, author, and date. For more details
+#' see the documentation on R Markdown \link[=rmd_metadata]{metadata}.
+#'
+#' R Markdown documents also support citations. You can find more information on
+#' the markdown syntax for citations in the
+#' \href{https://pandoc.org/MANUAL.html#citations}{Bibliographies
+#' and Citations} article in the online documentation.
+#' @inheritParams rmarkdown::pdf_document
+#' @inheritParams rmarkdown::html_document
+#' @param reference_docx Use the specified file as a style reference in
+#'   producing a docx file. For best results, the reference docx should be a
+#'   modified version of a docx file produced using pandoc. Pass "default"
+#'   to use the rmarkdown default styles.
+#' @param cover_page Cover page document file name.
+#' @param cover_title Title to be used in the cover page.
+#' @param cover_subtitle Subtitle to be used in the cover page.
+#' @param cover_date Date to be used in the cover page.
+#' @return R Markdown output format to pass to \code{\link{render}}
+#' @examples
+#' \dontrun{
+#' library(rmarkdown)
+#' library(phstemplates)
+#' render("input.Rmd", phs_report_docx())
+#' }
+#' @export
+phs_report_docx <- function(toc = FALSE,
+                            toc_depth = 3,
+                            number_sections = FALSE,
+                            fig_width = 5,
+                            fig_height = 4,
+                            fig_caption = TRUE,
+                            df_print = "default",
+                            highlight = "default",
+                            reference_docx = "default",
+                            keep_md = FALSE,
+                            md_extensions = NULL,
+                            pandoc_args = NULL,
+                            cover_page = NULL,
+                            cover_title = "Title",
+                            cover_subtitle = "Subtitle",
+                            cover_date = "DD Month YYYY") {
+
+  resolve_highlight <- utils::getFromNamespace("resolve_highlight", "rmarkdown")
+  highlighters <- utils::getFromNamespace("highlighters", "rmarkdown")
+  reference_intermediates_generator <- utils::getFromNamespace("reference_intermediates_generator", "rmarkdown")
+
+  # knitr options and hooks
+  knitr <- rmarkdown::knitr_options(
+    opts_chunk = list(dev = 'png',
+                      dpi = 96,
+                      fig.width = fig_width,
+                      fig.height = fig_height)
+  )
+
+  # base pandoc options for all docx output
+  args <- c()
+
+  # table of contents
+  args <- c(args, rmarkdown::pandoc_toc_args(toc, toc_depth))
+
+  # Lua filters (added if pandoc > 2)
+  lua_filters <- rmarkdown::pkg_file_lua("pagebreak.lua")
+
+  # numbered sections
+  if (number_sections) {
+    if (rmarkdown::pandoc_available("2.10.1")) {
+      args <- c(args, "--number-sections")
+    } else {
+      lua_filters <- c(lua_filters, rmarkdown::pkg_file_lua("number-sections.lua"))
+    }
+  }
+
+  # highlighting
+  if (!is.null(highlight)) highlight <- resolve_highlight(highlight, highlighters())
+  args <- c(args, rmarkdown::pandoc_highlight_args(highlight))
+
+  # reference docx
+  args <- c(args, reference_doc_args("docx", reference_docx))
+
+  # pandoc args
+  args <- c(args, pandoc_args)
+
+  saved_files_dir <- NULL
+  pre_processor <- function(metadata, input_file, runtime, knit_meta, files_dir, output_dir) {
+    saved_files_dir <<- files_dir
+    NULL
+  }
+
+  intermediates_generator <- function(...) {
+    reference_intermediates_generator(saved_files_dir, ..., reference_docx)
+  }
+
+  post_processor <- function(metadata, input_file, output_file, clean, verbose,
+                             cover = cover_page, title = cover_title,
+                             stitle = cover_subtitle, dt = cover_date,
+                             tocd = toc_depth) {
+
+    officer::read_docx(output_file) %>%
+      officer::cursor_reach(keyword = "Introduction") %>%
+      officer::body_add_toc(pos = "before", level = tocd) %>%
+      officer::body_add_par("Contents", pos = "before", style = "TOC Heading") %>%
+      officer::cursor_reach(keyword = "Introduction") %>%
+      officer::body_add_break(pos = "before") %>%
+      print(output_file)
+
+    # Cover Page
+    cover_page <- officer::read_docx(cover) %>%
+      officer::body_replace_all_text("Title", title) %>%
+      officer::body_replace_all_text("Subtitle", stitle) %>%
+      officer::body_replace_all_text("DD Month YYYY", dt)
+
+    # Combine Cover and Report
+    cover_page %>%
+      officer::cursor_end() %>%
+      officer::body_remove() %>%
+      officer::body_add_break() %>%
+      officer::body_add_docx(output_file) %>%
+      officer::set_doc_properties(title = title) %>%
+      print(output_file)
+  }
+
+  # return output format
+  rmarkdown::output_format(
+    knitr = knitr,
+    pandoc = rmarkdown::pandoc_options(to = "docx",
+                                       from = rmarkdown::from_rmarkdown(fig_caption, md_extensions),
+                                       args = args,
+                                       lua_filters = lua_filters),
+    keep_md = keep_md,
+    df_print = df_print,
+    pre_processor = pre_processor,
+    intermediates_generator = intermediates_generator,
+    post_processor = post_processor
+  )
+}
+
+reference_doc_args <- function(type, doc) {
+  if (is.null(doc) || identical(doc, "default")) return()
+  c(paste0("--reference-", if (rmarkdown::pandoc_available("2.0")) "doc" else {
+    match.arg(type, c("docx", "odt", "doc"))
+  }), rmarkdown::pandoc_path_arg(doc))
+}

README.md

@@ -41,7 +41,7 @@ install.packages("phstemplates")
 ```
 
 ## How to use
-To use this project template, install the package by following the instructions above. After doing this you will then be able to create new R projects with the recommended PHS structure within RStudio by clicking File -> New Project... -> New Directory and selecting PHS R Project Template. As usual, name the project and select a location for the project folder. The original author can also be input - this will automatically add the name to the top section of default scripts within the project. You can then edit the files and folders as appropriate, e.g. rename the R script files or create new sub-folders. The default files and folders contained within the project are described in subsequent sections of this README.
+To use this project template, install the package by following the instructions above. After doing this you will then be able to create new R projects with the recommended PHS structure within RStudio by clicking **File -> New Project... -> New Directory and selecting PHS R Project Template**. Name the project and select a location for the project folder. The original author can also be input - this will automatically add the name to the top section of default scripts within the project. You can then edit the files and folders as appropriate, e.g. rename the R script files or create new sub-folders. The default files and folders contained within the project are described in subsequent sections of this README.
 
 This template aims to instil best practice within PHS and therefore git has been initialised for version control. However, if you are not using this then you can delete the .gitignore file. More information about [version control](https://github.com/Public-Health-Scotland/resources/blob/master/version-control.md).
 
@@ -66,11 +66,9 @@ This template is also intended to be flexible, so you may not require every file
   * `r-project.Proj` - R project
 
 ## RMarkdown Templates
-This package currently provides a number of RMarkdown templates including templates for PHS national statistics report and summary documents but please note that these require pandoc v2 (or RStudio v1.2 which comes with the required version of pandoc). 
+This package currently provides a number of RMarkdown templates including templates for PHS national statistics report and summary documents but please note that these require pandoc v2 (or RStudio v1.2 which comes with the required version of pandoc). You can check the version of pandoc that you have with `rmarkdown::pandoc_version()`.
 
-You can access these templates in RStudio by clicking File -> New File -> R Markdown -> From Template. Then you can give it a template name.
-
-**Please note that after loading the report templates, you need to update your working directory. Instructions to do this are included at the top of the RMarkdown template file.**
+You can access these templates in RStudio by clicking **File -> New File -> R Markdown -> From Template**.
 
 ### Adding a new template
 1. Clone phstemplates and load it up in RStudio