Merge branch 'main' of https://github.com/insightsengineering/teal.re…

…porter
insightsengineering · Jan 23, 2024 · 89d2ebc · 89d2ebc
2 parents a54a41c + 7562421
commit 89d2ebc
Show file tree

Hide file tree

Showing 29 changed files with 1,096 additions and 202 deletions.
diff --git a/.Rbuildignore b/.Rbuildignore
@@ -1,7 +1,6 @@
 ^assets$
 ^venv$
 LICENSE
-dev/internal_examples.R
 ^.*\.Rproj$
 ^Jenkinsfile$
 ^Makefile$

diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,7 +1,7 @@
 Package: teal.reporter
 Title: Reporting Tools for 'shiny' Modules
-Version: 0.2.1.9014
-Date: 2023-12-13
+Version: 0.2.1.9015
+Date: 2024-01-18
 Authors@R: c(
     person("Dawid", "Kaledkowski", , "[email protected]", role = "cre"),
     person("Maciej", "Nasinski", role = "aut"),

diff --git a/NEWS.md b/NEWS.md
@@ -1,4 +1,4 @@
-# teal.reporter 0.2.1.9014
+# teal.reporter 0.2.1.9015
 
 * `add_card_button_srv` allows to specify `card_fun` with `label` parameter for card's title & content customization.
 

diff --git a/R/Archiver.R b/R/Archiver.R
@@ -6,6 +6,9 @@ Archiver <- R6::R6Class( # nolint: object_name_linter.
     #' @description Returns an `Archiver` object.
     #'
     #' @return an `Archiver` object
+    #' @examples
+    #' Archiver <- getFromNamespace("Archiver", "teal.reporter")
+    #' Archiver$new()
     initialize = function() {
       invisible(self)
     },
@@ -36,6 +39,9 @@ FileArchiver <- R6::R6Class( # nolint: object_name_linter.
     #' @description Returns a `FileArchiver` object.
     #'
     #' @return a `FileArchiver` object
+    #' @examples
+    #' FileArchiver <- getFromNamespace("FileArchiver", "teal.reporter")
+    #' FileArchiver$new()
     initialize = function() {
       tmp_dir <- tempdir()
       output_dir <- file.path(tmp_dir, sprintf("archive_%s", gsub("[.]", "", format(Sys.time(), "%Y%m%d%H%M%OS4"))))
@@ -50,6 +56,9 @@ FileArchiver <- R6::R6Class( # nolint: object_name_linter.
     #' @description get `output_dir` field
     #'
     #' @return `character` a `output_dir` field path.
+    #' @examples
+    #' FileArchiver <- getFromNamespace("FileArchiver", "teal.reporter")
+    #' FileArchiver$new()$get_output_dir()
     get_output_dir = function() {
       private$output_dir
     }
@@ -70,6 +79,24 @@ JSONArchiver <- R6::R6Class( # nolint: object_name_linter.
     #' @param reporter `Reporter` instance.
     #'
     #' @return invisibly self
+    #' @examples
+    #' ReportCard <- getFromNamespace("ReportCard", "teal.reporter")
+    #' card1 <- ReportCard$new()
+    #'
+    #' card1$append_text("Header 2 text", "header2")
+    #' card1$append_text("A paragraph of default text", "header2")
+    #' card1$append_plot(
+    #'  ggplot2::ggplot(iris, ggplot2::aes(x = Petal.Length)) + ggplot2::geom_histogram()
+    #' )
+    #'
+    #' Reporter <- getFromNamespace("Reporter", "teal.reporter")
+    #' reporter <- Reporter$new()
+    #' reporter$append_cards(list(card1))
+    #'
+    #' JSONArchiver <- getFromNamespace("JSONArchiver", "teal.reporter")
+    #' archiver <- JSONArchiver$new()
+    #' archiver$write(reporter)
+    #' archiver$get_output_dir()
     write = function(reporter) {
       checkmate::assert_class(reporter, "Reporter")
       unlink(list.files(private$output_dir, recursive = TRUE, full.names = TRUE))
@@ -81,6 +108,31 @@ JSONArchiver <- R6::R6Class( # nolint: object_name_linter.
     #' @param path `character(1)` a path to the directory with all proper files.
     #'
     #' @return `Reporter` instance.
+    #' @examples
+    #' ReportCard <- getFromNamespace("ReportCard", "teal.reporter")
+    #' card1 <- ReportCard$new()
+    #'
+    #' card1$append_text("Header 2 text", "header2")
+    #' card1$append_text("A paragraph of default text", "header2")
+    #' card1$append_plot(
+    #'  ggplot2::ggplot(iris, ggplot2::aes(x = Petal.Length)) + ggplot2::geom_histogram()
+    #' )
+    #'
+    #' Reporter <- getFromNamespace("Reporter", "teal.reporter")
+    #' reporter <- Reporter$new()
+    #' reporter$append_cards(list(card1))
+    #'
+    #' JSONArchiver <- getFromNamespace("JSONArchiver", "teal.reporter")
+    #' archiver <- JSONArchiver$new()
+    #' archiver$write(reporter)
+    #' archiver$get_output_dir()
+    #'
+    #' archiver$read()$get_cards()[[1]]$get_content()
+    #' Reporter <- getFromNamespace("Reporter", "teal.reporter")
+    #' blocks <- Reporter$new()
+    #' blocks <- blocks$from_reporter(archiver$read())$get_blocks()
+    #' Renderer <- getFromNamespace("Renderer", "teal.reporter")
+    #' doc <- Renderer$new()$render(blocks)
     read = function(path = NULL) {
       checkmate::assert(
         checkmate::check_null(path),

diff --git a/R/ContentBlock.R b/R/ContentBlock.R
@@ -8,6 +8,10 @@ ContentBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @details Returns a `ContentBlock` object with no content and the default style.
     #'
     #' @return `ContentBlock`
+    #' @examples
+    #' ContentBlock <- getFromNamespace("ContentBlock", "teal.reporter")
+    #' ContentBlock$new()
+    #'
     initialize = function() {
       private$content <- character(0)
       invisible(self)
@@ -17,6 +21,11 @@ ContentBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @param content (`character(0)` or `character(1)`) a string literal or a file path assigned to this `ContentBlock`
     #'
     #' @return invisibly self
+    #' @examples
+    #' ContentBlock <- getFromNamespace("ContentBlock", "teal.reporter")
+    #' block <- ContentBlock$new()
+    #' block$set_content("Base64 encoded picture")
+    #'
     set_content = function(content) {
       checkmate::assert_character(content, min.len = 0, max.len = 1)
       private$content <- content
@@ -25,6 +34,11 @@ ContentBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @description Returns the absolute path to content of this `ContentBlock`
     #'
     #' @return `character` content of this `ContentBlock`
+    #' @examples
+    #' ContentBlock <- getFromNamespace("ContentBlock", "teal.reporter")
+    #' block <- ContentBlock$new()
+    #' block$get_content()
+    #'
     get_content = function() {
       private$content
     },

diff --git a/R/FileBlock.R b/R/FileBlock.R
@@ -17,6 +17,13 @@ FileBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @param output_dir `character` with a path to the directory where a file will be copied.
     #'
     #' @return invisibly self
+    #' @examples
+    #' FileBlock <- getFromNamespace("FileBlock", "teal.reporter")
+    #' block <- FileBlock$new()
+    #' file_path <- tempfile(fileext = ".png")
+    #' saveRDS(iris, file_path)
+    #' block$from_list(list(basename = basename(file_path)), dirname(file_path))
+    #'
     from_list = function(x, output_dir) {
       checkmate::assert_list(x)
       checkmate::assert_names(names(x), must.include = "basename")
@@ -33,6 +40,11 @@ FileBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @param output_dir `character` with a path to the directory where a file will be copied.
     #'
     #' @return `named list` with a `basename` of the file.
+    #' @examples
+    #' FileBlock <- getFromNamespace("FileBlock", "teal.reporter")
+    #' block <- FileBlock$new()
+    #' block$to_list(tempdir())
+    #'
     to_list = function(output_dir) {
       base_name <- basename(super$get_content())
       file.copy(super$get_content(), file.path(output_dir, base_name))

diff --git a/R/NewpageBlock.R b/R/NewpageBlock.R
@@ -9,6 +9,10 @@ NewpageBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @details Returns a `NewpageBlock` object with no content and the default style.
     #'
     #' @return `NewpageBlock`
+    #' @examples
+    #' NewpageBlock <- getFromNamespace("NewpageBlock", "teal.reporter")
+    #' block <- NewpageBlock$new()
+    #'
     initialize = function() {
       super$set_content("\n\\newpage\n")
       invisible(self)

diff --git a/R/PictureBlock.R b/R/PictureBlock.R
@@ -23,6 +23,18 @@ PictureBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @param content (`ggplot`, `grob`, `trellis`) a picture in this `PictureBlock`
     #'
     #' @return invisibly self
+    #' @examples
+    #' PictureBlock <- getFromNamespace("PictureBlock", "teal.reporter")
+    #' block <- PictureBlock$new()
+    #' block$set_content(ggplot2::ggplot(iris))
+    #'
+    #' PictureBlock <- getFromNamespace("PictureBlock", "teal.reporter")
+    #' block <- PictureBlock$new()
+    #' block$set_content(lattice::bwplot(1))
+    #'
+    #' PictureBlock <- getFromNamespace("PictureBlock", "teal.reporter")
+    #' block <- PictureBlock$new()
+    #' block$set_content(ggplot2::ggplotGrob(ggplot2::ggplot(iris)))
     set_content = function(content) {
       checkmate::assert_multi_class(content, private$supported_plots)
       path <- tempfile(fileext = ".png")
@@ -51,6 +63,11 @@ PictureBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @param title (`character(1)`) a string assigned to this `PictureBlock`
     #'
     #' @return invisibly self
+    #' @examples
+    #' PictureBlock <- getFromNamespace("PictureBlock", "teal.reporter")
+    #' block <- PictureBlock$new()
+    #' block$set_title("Title")
+    #'
     set_title = function(title) {
       checkmate::assert_string(title)
       private$title <- title
@@ -59,6 +76,10 @@ PictureBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @description Returns the title of this `PictureBlock`
     #'
     #' @return the content of this `PictureBlock`
+    #' PictureBlock <- getFromNamespace("PictureBlock", "teal.reporter")
+    #' block <- PictureBlock$new()
+    #' block$get_title()
+    #'
     get_title = function() {
       private$title
     },
@@ -67,6 +88,11 @@ PictureBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @param dim `numeric` figure dimensions (width and height) in pixels, length 2.
     #'
     #' @return `self`
+    #' @examples
+    #' PictureBlock <- getFromNamespace("PictureBlock", "teal.reporter")
+    #' block <- PictureBlock$new()
+    #' block$set_dim(c(800, 600))
+    #'
     set_dim = function(dim) {
       checkmate::assert_numeric(dim, len = 2)
       private$dim <- dim
@@ -75,6 +101,10 @@ PictureBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @description Returns the dimensions of this `PictureBlock`
     #'
     #' @return `numeric` the array of 2 numeric values representing width and height in pixels.
+    #' @examples
+    #' PictureBlock <- getFromNamespace("PictureBlock", "teal.reporter")
+    #' block <- PictureBlock$new()
+    #' block$get_dim()
     get_dim = function() {
       private$dim
     }

diff --git a/R/RcodeBlock.R b/R/RcodeBlock.R
@@ -12,6 +12,10 @@ RcodeBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @param ... any `rmarkdown` R chunk parameter and it value.
     #'
     #' @return `RcodeBlock`
+    #' @examples
+    #' RcodeBlock <- getFromNamespace("RcodeBlock", "teal.reporter")
+    #' block <- RcodeBlock$new()
+    #'
     initialize = function(content = character(0), ...) {
       super$set_content(content)
       self$set_params(list(...))
@@ -24,6 +28,11 @@ RcodeBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @param params (`list`) any `rmarkdown` R chunk parameter and its value.
     #'
     #' @return invisibly self
+    #' @examples
+    #' RcodeBlock <- getFromNamespace("RcodeBlock", "teal.reporter")
+    #' block <- RcodeBlock$new()
+    #' block$set_params(list(echo = TRUE))
+    #'
     set_params = function(params) {
       checkmate::assert_list(params, names = "named")
       checkmate::assert_subset(names(params), self$get_available_params())
@@ -33,12 +42,22 @@ RcodeBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @description Returns the parameters of this `RcodeBlock`.
     #'
     #' @return `character` the parameters of this `RcodeBlock`
+    #' @examples
+    #' RcodeBlock <- getFromNamespace("RcodeBlock", "teal.reporter")
+    #' block <- RcodeBlock$new()
+    #' block$get_params()
+    #'
     get_params = function() {
       private$params
     },
     #' @description Returns an array of parameters available to this `RcodeBlock`.
     #'
     #' @return a `character` array of parameters
+    #' @examples
+    #' RcodeBlock <- getFromNamespace("RcodeBlock", "teal.reporter")
+    #' block <- RcodeBlock$new()
+    #' block$get_available_params()
+    #'
     get_available_params = function() {
       names(knitr::opts_chunk$get())
     },
@@ -48,6 +67,11 @@ RcodeBlock <- R6::R6Class( # nolint: object_name_linter.
     #' Use the `get_available_params` method to get all possible parameters.
     #'
     #' @return invisibly self
+    #' @examples
+    #' RcodeBlock <- getFromNamespace("RcodeBlock", "teal.reporter")
+    #' block <- RcodeBlock$new()
+    #' block$from_list(list(text = "sth", params = list()))
+    #'
     from_list = function(x) {
       checkmate::assert_list(x)
       checkmate::assert_names(names(x), must.include = c("text", "params"))
@@ -58,6 +82,11 @@ RcodeBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @description Convert the `RcodeBlock` to a list.
     #'
     #' @return `named list` with a text and `params`.
+    #' @examples
+    #' RcodeBlock <- getFromNamespace("RcodeBlock", "teal.reporter")
+    #' block <- RcodeBlock$new()
+    #' block$to_list()
+    #'
     to_list = function() {
       list(text = self$get_content(), params = self$get_params())
     }