Merge pull request #8 from A2-ai/bug_fix_rm

Fixed bug in finalize_document and added better argument descriptions/labels for the package

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: reportifyr
-Title: Create reproducible reports with quarto and word 
-Version: 0.2.5
+Title: Reproducible Reporting Made Simple in R
+Version: 0.2.6
 Authors@R: c(
     person("Jacob", "Dumbleton", , "[email protected]", role = c("aut", "cre")),
     person("Matthew", "Smith", , "[email protected]", role = "aut"),
@@ -16,7 +16,7 @@ Authors@R: c(
     person("Wesley", "Cummings", , "[email protected]", role = "ctb"),
     person("Elizabeth", "LeBeau", ,"[email protected]", role = "ctb")
   )
-Description: A tool to extend quarto's ability to be a starting point for fully featured word reports. 
+Description: Create reproducible reports with Microsoft Word and R.
 License: GPL (>= 3)
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
@@ -47,5 +47,4 @@ Suggests:
     testthat (>= 3.0.0)
 Config/testthat/edition: 3
 LazyData: true
-VignetteBuilder: knitr
 URL: https://a2-ai.github.io/reportifyr/

R/add_footnotes.R

@@ -1,14 +1,14 @@
-#' Inserts Footnotes in appropriate places in Word files
+#' Inserts Footnotes in appropriate places in a Microsoft Word file
 #'
-#' @description Reads in a .docx file and returns a new version with footnotes placed at appropriate places in the document.
-#' @param docx_in Path to the input .docx file
-#' @param docx_out Path to output .docx to save to
-#' @param figures_path Path to images and associated metadata directory
-#' @param tables_path Path to tables and associated metadata directory
-#' @param footnotes Path to standard_footnotes.yaml
-#' @param include_object_path Boolean for including object path path in footnotes
-#' @param footnotes_fail_on_missing_metadata Boolean for allowing objects to lack metadata and thus have no footnotes
-#' @param debug Debug
+#' @description Reads in a `.docx` file and returns a new version with footnotes placed at appropriate places in the document.
+#' @param docx_in The file path to the input `.docx` file.
+#' @param docx_out The file path to the output `.docx` file to save to.
+#' @param figures_path The file path to the figures and associated metadata directory.
+#' @param tables_path The file path to the tables and associated metadata directory.
+#' @param standard_footnotes_yaml The file path to the `standard_footnotes.yaml`. Default is `NULL`. If `NULL`, a default `standard_footnotes.yaml` bundled with the `reportifyr` package is used.
+#' @param include_object_path A boolean indicating whether to include the file path of the figure or table in the footnotes. Default is `FALSE`.
+#' @param footnotes_fail_on_missing_metadata A boolean indicating whether to stop execution if the metadata `.json` file for a figure or table is missing. Default is `TRUE`.
+#' @param debug Debug.
 #'
 #' @export
 #'
@@ -17,25 +17,25 @@
 #' # ---------------------------------------------------------------------------
 #' # Load all dependencies
 #' # ---------------------------------------------------------------------------
-#' docx_in <- file.path(here::here(), "report", "shell", "template.docx")
+#' docx_in <- here::here("report", "shell", "template.docx")
 #' doc_dirs <- make_doc_dirs(docx_in = docx_in)
-#' figures_path <- file.path(here::here(), "OUTPUTS", "figures")
-#' tables_path <- file.path(here::here(), "OUTPUTS", "tables")
-#' footnotes <- file.path(here::here(), "report", "standard_footnotes.yaml")
+#' figures_path <- here::here("OUTPUTS", "figures")
+#' tables_path <- here::here("OUTPUTS", "tables")
+#' standard_footnotes_yaml <- here::here("report", "standard_footnotes.yaml")
 #'
 #' # ---------------------------------------------------------------------------
 #' # Step 1.
-#' # Table addition running add_tables will format and insert tables into the doc.
+#' # `add_tables()` will format and insert tables into the `.docx` file.
 #' # ---------------------------------------------------------------------------
 #' add_tables(
-#'   docx_in = docx_in,
+#'   docx_in = doc_dirs$doc_in,
 #'   docx_out = doc_dirs$doc_tables,
 #'   tables_path = tables_path
 #' )
 #'
 #' # ---------------------------------------------------------------------------
 #' # Step 2.
-#' # Next we place in the plots using the add_plots function.
+#' # Next we insert the plots using the `add_plots()` function.
 #' # ---------------------------------------------------------------------------
 #' add_plots(
 #'   docx_in = doc_dirs$doc_tables,
@@ -45,26 +45,26 @@
 #'
 #' # ---------------------------------------------------------------------------
 #' # Step 3.
-#' # Now we can add the footnotes to all the inserted figures and tables.
+#' # Now we can add the footnotes with the `add_footnotes` function.
 #' # ---------------------------------------------------------------------------
 #' add_footnotes(
 #'   docx_in = doc_dirs$doc_tabs_figs,
 #'   docx_out = doc_dirs$doc_draft,
 #'   figures_path = figures_path,
 #'   tables_path = tables_path,
-#'   footnotes = footnotes,
-#'   include_object_path = TRUE
-#'   footnotes_fail_on_missing_metadata
+#'   standard_footnotes_yaml = standard_footnotes_yaml,
+#'   include_object_path = FALSE,
+#'   footnotes_fail_on_missing_metadata = TRUE
 #' )
 #' }
 add_footnotes <- function(docx_in,
                           docx_out,
                           figures_path,
                           tables_path,
-                          footnotes = NULL,
+                          standard_footnotes_yaml = NULL,
                           include_object_path = FALSE,
                           footnotes_fail_on_missing_metadata = TRUE,
-                          debug = F) {
+                          debug = FALSE) {
   log4r::debug(.le$logger, "Starting add_footnotes function")
 
   tictoc::tic()
@@ -97,10 +97,10 @@ add_footnotes <- function(docx_in,
   tab_script <- system.file("scripts/add_table_footnotes.py", package = "reportifyr")
   tab_args <- c("run", tab_script, "-i", docx_out, "-o", docx_out, "-d", tables_path, "-b", include_object_path, "-m", footnotes_fail_on_missing_metadata)
 
-  if (!is.null(footnotes)) {
-    log4r::info(.le$logger, paste0("Using provided footnotes file: ", footnotes))
-    fig_args <- c(fig_args, "-f", footnotes)
-    tab_args <- c(tab_args, "-f", footnotes)
+  if (!is.null(standard_footnotes_yaml)) {
+    log4r::info(.le$logger, paste0("Using provided footnotes file: ", standard_footnotes_yaml))
+    fig_args <- c(fig_args, "-f", standard_footnotes_yaml)
+    tab_args <- c(tab_args, "-f", standard_footnotes_yaml)
   } else {
     footnotes_file <- system.file("extdata/standard_footnotes.yaml", package = "reportifyr")
     log4r::info(.le$logger, paste0("Using default footnotes file: ", footnotes_file))

R/add_plots.R

@@ -1,12 +1,12 @@
-#' Inserts Figures in appropriate places in Word files
+#' Inserts Figures in appropriate places in a Microsoft Word file
 #'
-#' @description Reads in a .docx file and returns a new version with figures placed at appropriate places in the document.
-#' @param docx_in Path to the input .docx file
-#' @param docx_out Path to output .docx to save to
-#' @param figures_path Path to images file directory
-#' @param fig_width Figure width in inches. This is a global controller. Defaults to NULL. If NULL, the size is calculated calculated based on the pixels of the actual figure
-#' @param fig_height Figure height in inches. This is a global controller. Defaults to NULL. If NULL, the size is automatically calculated based on the pixels of the actual figure
-#' @param debug Debug
+#' @description Reads in a `.docx` file and returns a new version with figures placed at appropriate places in the document.
+#' @param docx_in The file path to the input `.docx` file.
+#' @param docx_out The file path to the output `.docx` file to save to.
+#' @param figures_path The file path to the figures directory.
+#' @param fig_width A global controller. The figure width in inches. Default is `NULL`. If `NULL`, the width is determined by the figure's pixel dimensions.
+#' @param fig_height A global controller. The figure height in inches. Default is `NULL`. If `NULL`, the height is determined by the figure's pixel dimensions.
+#' @param debug Debug.
 #'
 #' @export
 #'
@@ -15,15 +15,15 @@
 #' # ---------------------------------------------------------------------------
 #' # Load all dependencies
 #' # ---------------------------------------------------------------------------
-#' docx_in <- file.path(here::here(), "report", "shell", "template.docx")
+#' docx_in <- here::here("report", "shell", "template.docx")
 #' doc_dirs <- make_doc_dirs(docx_in = docx_in)
-#' figures_path <- file.path(here::here(), "OUTPUTS", "figures")
-#' tables_path <- file.path(here::here(), "OUTPUTS", "tables")
-#' footnotes <- file.path(here::here(), "report", "standard_footnotes.yaml")
+#' figures_path <- here::here("OUTPUTS", "figures")
+#' tables_path <- here::here("OUTPUTS", "tables")
+#' standard_footnotes_yaml <- here::here("report", "standard_footnotes.yaml")
 #'
 #' # ---------------------------------------------------------------------------
 #' # Step 1.
-#' # Table addition running add_tables will format and insert tables into the doc.
+#' # `add_tables()` will format and insert tables into the `.docx` file.
 #' # ---------------------------------------------------------------------------
 #' add_tables(
 #'   docx_in = doc_dirs$doc_in,
@@ -32,8 +32,8 @@
 #' )
 #'
 #' # ---------------------------------------------------------------------------
-#' # Step 3.
-#' # Next we place in the plots using the add_plots function.
+#' # Step 2.
+#' # Next we insert the plots using the `add_plots()` function.
 #' # ---------------------------------------------------------------------------
 #' add_plots(
 #'   docx_in = doc_dirs$doc_tables,
@@ -46,7 +46,7 @@ add_plots <- function(docx_in,
                       figures_path,
                       fig_width = NULL,
                       fig_height = NULL,
-                      debug = F) {
+                      debug = FALSE) {
   log4r::debug(.le$logger, "Starting add_plots function")
 
   tictoc::tic()

R/add_tables.R

@@ -1,33 +1,38 @@
-#' Adds tables by looking for magic string
+#' Inserts Tables in appropriate places in a Microsoft Word file
 #'
-#' @param docx_in input doc
-#' @param docx_out output doc
-#' @param tables_path path to tables file
-#' @param debug debug mode
+#' @description Reads in a `.docx` file and returns a new version with tables placed at appropriate places in the document.
+#' @param docx_in The file path to the input `.docx` file.
+#' @param docx_out The file path to the output `.docx` file to save to.
+#' @param tables_path The file path to the tables and associated metadata directory.
+#' @param debug Debug.
 #'
 #' @export
 #'
 #' @examples \dontrun{
+#'
 #' # ---------------------------------------------------------------------------
 #' # Load all dependencies
 #' # ---------------------------------------------------------------------------
-#' docx_in <- file.path(here::here(), "report", "shell", "template.docx")
+#' docx_in <- here::here("report", "shell", "template.docx")
 #' doc_dirs <- make_doc_dirs(docx_in = docx_in)
-#' figures_path <- file.path(here::here(), "OUTPUTS", "figures")
-#' tables_path <- file.path(here::here(), "OUTPUTS", "tables")
-#' footnotes <- file.path(here::here(), "report", "standard_footnotes.yaml")
+#' figures_path <- here::here("OUTPUTS", "figures")
+#' tables_path <- here::here("OUTPUTS", "tables")
+#' standard_footnotes_yaml <- here::here("report", "standard_footnotes.yaml")
 #'
 #' # ---------------------------------------------------------------------------
 #' # Step 1.
-#' # Table addition running add_tables will format and insert tables into the doc.
+#' # `add_tables()` will format and insert tables into the `.docx` file.
 #' # ---------------------------------------------------------------------------
 #' add_tables(
-#'   docx_in = doc_dirs$doc_clean,
+#'   docx_in = doc_dirs$doc_in,
 #'   docx_out = doc_dirs$doc_tables,
 #'   tables_path = tables_path
 #' )
 #' }
-add_tables <- function(docx_in, docx_out, tables_path, debug = F) {
+add_tables <- function(docx_in,
+                       docx_out,
+                       tables_path,
+                       debug = FALSE) {
   log4r::debug(.le$logger, "Starting add_tables function")
   tictoc::tic()
 

R/build_report.R

@@ -1,14 +1,14 @@
-#' Updates a Word file to include formatted plots, tables, and footnotes
+#' Updates a Microsoft Word file to include formatted plots, tables, and footnotes
 #'
-#' @description Reads in a .docx file and returns an updated version with plots, tables, and footnotes replaced.
-#' @param docx_in Path to input .docx to update
-#' @param docx_out Path to output .docx to save to
-#' @param figures_path Path to images file directory
-#' @param tables_path Path to tables file directory
-#' @param standard_footnotes_yaml Path to standard_footnotes.yaml in report
-#' @param add_footnotes boolean for including footnotes in the document or not
-#' @param include_object_path boolean for including object path in footnotes
-#' @param footnotes_fail_on_missing_metadata Boolean for allowing objects to lack metadata and thus have no footnotes
+#' @description Reads in a `.docx` file and returns a new version with plots, tables, and footnotes replaced.
+#' @param docx_in The file path to the input `.docx` file.
+#' @param docx_out The file path to the output `.docx` file to save to. Default is `NULL`.
+#' @param figures_path The file path to the figures and associated metadata directory.
+#' @param tables_path The file path to the tables and associated metadata directory.
+#' @param standard_footnotes_yaml The file path to the `standard_footnotes.yaml`. Default is `NULL`. If `NULL`, a default `standard_footnotes.yaml` bundled with the `reportifyr` package is used.
+#' @param add_footnotes A boolean indicating whether to insert footnotes into the `docx_in` or not. Default is `TRUE`.
+#' @param include_object_path A boolean indicating whether to include the file path of the figure or table in the footnotes. Default is `FALSE`.
+#' @param footnotes_fail_on_missing_metadata A boolean indicating whether to stop execution if the metadata `.json` file for a figure or table is missing. Default is `TRUE`.
 #'
 #' @export
 #'
@@ -17,22 +17,23 @@
 #' # ---------------------------------------------------------------------------
 #' # Load all dependencies
 #' # ---------------------------------------------------------------------------
-#' docx_in <- file.path(here::here(), "report", "shell", "template.docx")
-#' figures_path <- file.path(here::here(), "OUTPUTS", "figures")
-#' tables_path <- file.path(here::here(), "OUTPUTS", "tables")
-#' footnotes <- file.path(here::here(), "report", "standard_footnotes.yaml")
+#' docx_in <- here::here("report", "shell", "template.docx")
+#' doc_dirs <- make_doc_dirs(docx_in = docx_in)
+#' figures_path <- here::here("OUTPUTS", "figures")
+#' tables_path <- here::here("OUTPUTS", "tables")
+#' standard_footnotes_yaml <- here::here("report", "standard_footnotes.yaml")
 #'
 #' # ---------------------------------------------------------------------------
 #' # Step 1.
-#' # Run the wrapper function to replace figures, tables, and footnotes in a
-#' # .docx file.
+#' # Run the `build_report()` wrapper function to replace figures, tables, and
+#' # footnotes in a `.docx` file.
 #' # ---------------------------------------------------------------------------
 #' build_report(
-#'   docx_in = docx_in,
+#'   docx_in = doc_dirs$doc_in,
 #'   docx_out = doc_dirs$doc_draft,
 #'   figures_path = figures_path,
 #'   tables_path = tables_path,
-#'   standard_footnotes_yaml = footnotes
+#'   standard_footnotes_yaml = standard_footnotes_yaml
 #' )
 #' }
 build_report <- function(docx_in,
@@ -102,7 +103,7 @@ build_report <- function(docx_in,
           docx_out = docx_out,
           figures_path = figures_path,
           tables_path = tables_path,
-          footnotes = standard_footnotes_yaml,
+          standard_footnotes_yaml = standard_footnotes_yaml,
           include_object_path = include_object_path,
           footnotes_fail_on_missing_metadata = footnotes_fail_on_missing_metadata
         )

R/finalize_document.R

@@ -1,8 +1,8 @@
-#' Finalizes the document by removing magic strings and bookmarks
+#' Finalizes the Microsoft Word file by removing magic strings and bookmarks
 #'
-#' @description Reads in a .docx file and returns a finalized version with magic strings and bookmarks removed.
-#' @param docx_in Path to input .docx to finalize
-#' @param docx_out Path to output .docx to save to
+#' @description Reads in a `.docx` file and returns a finalized version with magic strings and bookmarks removed.
+#' @param docx_in The file path to the input `.docx` file.
+#' @param docx_out The file path to the output `.docx` file to save to. Default is `NULL`. If `NULL`, `docx_out` is assigned `doc_dirs$doc_final` using `make_doc_dirs(docx_in = docx_in)`.
 #'
 #' @export
 #'
@@ -11,27 +11,30 @@
 #' # ---------------------------------------------------------------------------
 #' # Load all dependencies
 #' # ---------------------------------------------------------------------------
-#' docx_in <- file.path(here::here(), "report", "shell", "template.docx")
-#' figures_path <- file.path(here::here(), "OUTPUTS", "figures")
-#' tables_path <- file.path(here::here(), "OUTPUTS", "tables")
-#' footnotes <- file.path(here::here(), "report", "standard_footnotes.yaml")
+#' docx_in <- here::here("report", "shell", "template.docx")
+#' doc_dirs <- make_doc_dirs(docx_in = docx_in)
+#' figures_path <- here::here("OUTPUTS", "figures")
+#' tables_path <- here::here("OUTPUTS", "tables")
+#' standard_footnotes_yaml <- here::here("report", "standard_footnotes.yaml")
 #'
 #' # ---------------------------------------------------------------------------
 #' # Step 1.
-#' # Run the wrapper function build_report() to replace figures, tables, and
-#' # footnotes in a .docx file.
+#' # Run the `build_report()` wrapper function to replace figures, tables, and
+#' # footnotes in a `.docx` file.
 #' # ---------------------------------------------------------------------------
 #' build_report(
-#'   docx_in = docx_in,
+#'   docx_in = doc_dirs$doc_in,
 #'   docx_out = doc_dirs$doc_draft,
 #'   figures_path = figures_path,
 #'   tables_path = tables_path,
-#'   standard_footnotes_yaml = footnotes
+#'   standard_footnotes_yaml = standard_footnote_yaml
 #' )
 #'
 #' # ---------------------------------------------------------------------------
 #' # Step 2.
-#' # If you are happy with the report and are ready to finalize the document.
+#' # If you are ready to finalize the `.docx` file, run the `finalize_document()`
+#' # function. This will remove the ties between reportifyr and the document, so
+#' # please be mindful!
 #' # ---------------------------------------------------------------------------
 #' finalize_document(
 #'   docx_in = doc_dirs$doc_draft,

R/format_flextable.R

@@ -1,7 +1,7 @@
 #' Formats data frames to a flextable specification
 #'
-#' @param data_in Data frame to be formatted
-#' @param table1_format Boolean for using table1 formatting
+#' @param data_in The input data to be formatted. Must be either a data frame or a flextable object.
+#' @param table1_format A boolean indicating whether to apply table1-style formatting. Default is `FALSE`.
 #'
 #' @export
 #'
@@ -14,7 +14,7 @@
 #' )
 #' }
 format_flextable <- function(data_in,
-                             table1_format = F) {
+                             table1_format = FALSE) {
   log4r::debug(.le$logger, "Starting format_flextable function")
 
   assertthat::assert_that(