bring back examples for internal functions

insightsengineering · Jan 16, 2024 · 8328e83 · 8328e83
1 parent a54a41c
commit 8328e83
Show file tree

Hide file tree

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

diff --git a/R/Archiver.R b/R/Archiver.R
@@ -6,6 +6,8 @@ Archiver <- R6::R6Class( # nolint: object_name_linter.
     #' @description Returns an `Archiver` object.
     #'
     #' @return an `Archiver` object
+    #' @examples
+    #' archiver <- getFromNamespace("Archiver", "teal.reporter")$new()
     initialize = function() {
       invisible(self)
     },
@@ -36,6 +38,8 @@ FileArchiver <- R6::R6Class( # nolint: object_name_linter.
     #' @description Returns a `FileArchiver` object.
     #'
     #' @return a `FileArchiver` object
+    #' @examples
+    #' archiver <- getFromNamespace("FileArchiver", "teal.reporter")$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 +54,9 @@ FileArchiver <- R6::R6Class( # nolint: object_name_linter.
     #' @description get `output_dir` field
     #'
     #' @return `character` a `output_dir` field path.
+    #' @examples
+    #' archiver <- getFromNamespace("FileArchiver", "teal.reporter")$new()
+    #' archiver$get_output_dir()
     get_output_dir = function() {
       private$output_dir
     }
@@ -70,6 +77,21 @@ JSONArchiver <- R6::R6Class( # nolint: object_name_linter.
     #' @param reporter `Reporter` instance.
     #'
     #' @return invisibly self
+    #' @examples
+    #' card1 <- getFromNamespace("ReportCard", "teal.reporter")$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")$new()
+    #' reporter$append_cards(list(card1))
+    #'
+    #' archiver <- getFromNamespace("JSONArchiver", "teal.reporter")$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 +103,25 @@ JSONArchiver <- R6::R6Class( # nolint: object_name_linter.
     #' @param path `character(1)` a path to the directory with all proper files.
     #'
     #' @return `Reporter` instance.
+    #' @examples
+    #' card1 <- getFromNamespace("ReportCard", "teal.reporter")$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")$new()
+    #' reporter$append_cards(list(card1))
+    #'
+    #' archiver <- getFromNamespace("JSONArchiver", "teal.reporter")$new()
+    #' archiver$write(reporter)
+    #' archiver$get_output_dir()
+    #'
+    #' archiver$read()$get_cards()[[1]]$get_content()
+    #' blocks <- getFromNamespace("Reporter", "teal.reporter")$new()$from_reporter(archiver$read())$get_blocks()
+    #' doc <- getFromNamespace("Renderer", "teal.reporter")$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,9 @@ ContentBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @details Returns a `ContentBlock` object with no content and the default style.
     #'
     #' @return `ContentBlock`
+    #' @examples
+    #' block <- getFromNamespace("ContentBlock", "teal.reporter")$new()
+    #'
     initialize = function() {
       private$content <- character(0)
       invisible(self)
@@ -17,6 +20,10 @@ 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
+    #' block <- getFromNamespace("ContentBlock", "teal.reporter")$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 +32,10 @@ ContentBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @description Returns the absolute path to content of this `ContentBlock`
     #'
     #' @return `character` content of this `ContentBlock`
+    #' @examples
+    #' block <- getFromNamespace("ContentBlock", "teal.reporter")$new()
+    #' block$get_content()
+    #'
     get_content = function() {
       private$content
     },

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

diff --git a/R/PictureBlock.R b/R/PictureBlock.R
@@ -23,6 +23,15 @@ PictureBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @param content (`ggplot`, `grob`, `trellis`) a picture in this `PictureBlock`
     #'
     #' @return invisibly self
+    #' @examples
+    #' block <- getFromNamespace("PictureBlock", "teal.reporter")$new()
+    #' block$set_content(ggplot2::ggplot(iris))
+    #'
+    #' yblock <- getFromNamespace("PictureBlock", "teal.reporter")$new()
+    #' block$set_content(lattice::bwplot(1))
+    #'
+    #' block <- getFromNamespace("PictureBlock", "teal.reporter")$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 +60,10 @@ PictureBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @param title (`character(1)`) a string assigned to this `PictureBlock`
     #'
     #' @return invisibly self
+    #' @examples
+    #' block <- getFromNamespace("PictureBlock", "teal.reporter")$new()
+    #' block$set_title("Title")
+    #'
     set_title = function(title) {
       checkmate::assert_string(title)
       private$title <- title
@@ -59,6 +72,9 @@ PictureBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @description Returns the title of this `PictureBlock`
     #'
     #' @return the content of this `PictureBlock`
+    #' block <- getFromNamespace("PictureBlock", "teal.reporter")$new()
+    #' block$get_title()
+    #'
     get_title = function() {
       private$title
     },
@@ -67,6 +83,10 @@ PictureBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @param dim `numeric` figure dimensions (width and height) in pixels, length 2.
     #'
     #' @return `self`
+    #' @examples
+    #' block <- getFromNamespace("PictureBlock", "teal.reporter")$new()
+    #' block$set_dim(c(800, 600))
+    #'
     set_dim = function(dim) {
       checkmate::assert_numeric(dim, len = 2)
       private$dim <- dim
@@ -75,6 +95,9 @@ 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
+    #' block <- getFromNamespace("PictureBlock", "teal.reporter")$new()
+    #' block$get_dim()
     get_dim = function() {
       private$dim
     }

diff --git a/R/RcodeBlock.R b/R/RcodeBlock.R
@@ -12,6 +12,9 @@ RcodeBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @param ... any `rmarkdown` R chunk parameter and it value.
     #'
     #' @return `RcodeBlock`
+    #' @examples
+    #' block <- getFromNamespace("RcodeBlock", "teal.reporter")$new()
+    #'
     initialize = function(content = character(0), ...) {
       super$set_content(content)
       self$set_params(list(...))
@@ -24,6 +27,10 @@ RcodeBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @param params (`list`) any `rmarkdown` R chunk parameter and its value.
     #'
     #' @return invisibly self
+    #' @examples
+    #' block <- getFromNamespace("RcodeBlock", "teal.reporter")$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 +40,20 @@ RcodeBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @description Returns the parameters of this `RcodeBlock`.
     #'
     #' @return `character` the parameters of this `RcodeBlock`
+    #' @examples
+    #' block <- getFromNamespace("RcodeBlock", "teal.reporter")$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
+    #' block <- getFromNamespace("RcodeBlock", "teal.reporter")$new()
+    #' block$get_available_params()
+    #'
     get_available_params = function() {
       names(knitr::opts_chunk$get())
     },
@@ -48,6 +63,10 @@ RcodeBlock <- R6::R6Class( # nolint: object_name_linter.
     #' Use the `get_available_params` method to get all possible parameters.
     #'
     #' @return invisibly self
+    #' @examples
+    #' block <- getFromNamespace("RcodeBlock", "teal.reporter")$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 +77,10 @@ RcodeBlock <- R6::R6Class( # nolint: object_name_linter.
     #' @description Convert the `RcodeBlock` to a list.
     #'
     #' @return `named list` with a text and `params`.
+    #' @examples
+    #' block <- getFromNamespace("RcodeBlock", "teal.reporter")$new()
+    #' block$to_list()
+    #'
     to_list = function() {
       list(text = self$get_content(), params = self$get_params())
     }

diff --git a/R/Renderer.R b/R/Renderer.R
@@ -8,6 +8,9 @@ Renderer <- R6::R6Class( # nolint: object_name_linter.
     #' @details Returns a `Renderer` object.
     #'
     #' @return `Renderer` object.
+    #' @examples
+    #' renderer <- getFromNamespace("Renderer", "teal.reporter")$new()
+    #'
     initialize = function() {
       tmp_dir <- tempdir()
       output_dir <- file.path(tmp_dir, sprintf("report_%s", gsub("[.]", "", format(Sys.time(), "%Y%m%d%H%M%OS4"))))
@@ -28,6 +31,38 @@ Renderer <- R6::R6Class( # nolint: object_name_linter.
     #' @details `r global_knitr_details()`
     #'
     #' @return `character` a `Rmd` text (`yaml` header + body), ready to be rendered.
+    #' @examples
+    #' card1 <- getFromNamespace("ReportCard", "teal.reporter")$new()
+    #'
+    #' card1$append_text("Header 2 text", "header2")
+    #' card1$append_text("A paragraph of default text")
+    #' card1$append_plot(
+    #'  ggplot2::ggplot(iris, ggplot2::aes(x = Petal.Length)) + ggplot2::geom_histogram()
+    #' )
+    #'
+    #' card2 <- getFromNamespace("ReportCard", "teal.reporter")$new()
+    #'
+    #' card2$append_text("Header 2 text", "header2")
+    #' card2$append_text("A paragraph of default text", "header2")
+    #' lyt <- rtables::analyze(rtables::split_rows_by(rtables::basic_table(), "Day"), "Ozone", afun = mean)
+    #' table_res2 <- rtables::build_table(lyt, airquality)
+    #' card2$append_table(table_res2)
+    #' card2$append_table(iris)
+    #' card2$append_rcode("2+2", echo = FALSE)
+    #'
+    #' reporter <- getFromNamespace("Reporter", "teal.reporter")$new()
+    #' reporter$append_cards(list(card1, card2))
+    #'
+    #' yaml_l <- list(
+    #'   author = getFromNamespace("yaml_quoted", "teal.reporter")("NEST"),
+    #'   title = getFromNamespace("yaml_quoted", "teal.reporter")("Report"),
+    #'   date = getFromNamespace("yaml_quoted", "teal.reporter")("07/04/2019"),
+    #'   output = list(html_document = list(toc = FALSE))
+    #' )
+    #'
+    #' yaml_header <- getFromNamespace("md_header", "teal.reporter")(yaml::as.yaml(yaml_l))
+    #' result_path <- getFromNamespace("Renderer", "teal.reporter")$new()$renderRmd(reporter$get_blocks(), yaml_header)
+    #'
     renderRmd = function(blocks, yaml_header, global_knitr = getOption("teal.reporter.global_knitr")) {
       checkmate::assert_list(blocks, c("TextBlock", "PictureBlock", "NewpageBlock", "TableBlock", "RcodeBlock"))
       checkmate::assert_subset(names(global_knitr), names(knitr::opts_chunk$get()))
@@ -89,6 +124,35 @@ Renderer <- R6::R6Class( # nolint: object_name_linter.
     #' @details `r global_knitr_details()`
     #'
     #' @return `character` path to the output
+    #' @examples
+    #' card1 <- getFromNamespace("ReportCard", "teal.reporter")$new()
+    #' card1$append_text("Header 2 text", "header2")
+    #' card1$append_text("A paragraph of default text")
+    #' card1$append_plot(
+    #'  ggplot2::ggplot(iris, ggplot2::aes(x = Petal.Length)) + ggplot2::geom_histogram()
+    #' )
+    #'
+    #' card2 <- getFromNamespace("ReportCard", "teal.reporter")$new()
+    #' card2$append_text("Header 2 text", "header2")
+    #' card2$append_text("A paragraph of default text", "header2")
+    #' lyt <- rtables::analyze(rtables::split_rows_by(rtables::basic_table(), "Day"), "Ozone", afun = mean)
+    #' table_res2 <- rtables::build_table(lyt, airquality)
+    #' card2$append_table(table_res2)
+    #' card2$append_table(iris)
+    #' card2$append_rcode("2+2", echo = FALSE)
+    #' reporter <- getFromNamespace("Reporter", "teal.reporter")$new()
+    #' reporter$append_cards(list(card1, card2))
+    #'
+    #' yaml_l <- list(
+    #'   author = getFromNamespace("yaml_quoted", "teal.reporter")("NEST"),
+    #'   title = getFromNamespace("yaml_quoted", "teal.reporter")("Report"),
+    #'   date = getFromNamespace("yaml_quoted", "teal.reporter")("07/04/2019"),
+    #'   output = list(html_document = list(toc = FALSE))
+    #' )
+    #'
+    #' yaml_header <- getFromNamespace("md_header", "teal.reporter")(yaml::as.yaml(yaml_l))
+    #' result_path <- getFromNamespace("Renderer", "teal.reporter")$new()$render(reporter$get_blocks(), yaml_header)
+    #'
     render = function(blocks, yaml_header, global_knitr = getOption("teal.reporter.global_knitr"), ...) {
       args <- list(...)
       input_path <- self$renderRmd(blocks, yaml_header, global_knitr)
@@ -106,6 +170,10 @@ Renderer <- R6::R6Class( # nolint: object_name_linter.
     #' @description get `output_dir` field
     #'
     #' @return `character` a `output_dir` field path.
+    #' @examples
+    #' renderer <- getFromNamespace("Renderer", "teal.reporter")$new()
+    #' renderer$get_output_dir()
+    #'
     get_output_dir = function() {
       private$output_dir
     }

diff --git a/R/ReportCard.R b/R/ReportCard.R
@@ -76,10 +76,10 @@ ReportCard <- R6::R6Class( # nolint: object_name_linter.
     #'
     #' @param content (`ContentBlock`)
     #' @return invisibly self
+    #' @examples
+    #' card <- ReportCard$new()$append_content(getFromNamespace("NewpageBlock", "teal.reporter")$new())
     #'
     append_content = function(content) {
-      # example: # nolint
-      # card <- ReportCard$new()$append_content(teal.reporter:::NewpageBlock$new()) # nolint
       checkmate::assert_class(content, "ContentBlock")
       private$content <- append(private$content, content)
       invisible(self)

diff --git a/R/TableBlock.R b/R/TableBlock.R
@@ -24,6 +24,10 @@ TableBlock <- R6::R6Class( # nolint: object_name_linter.
     #'   this `TableBlock`
     #'
     #' @return invisibly self
+    #' @examples
+    #' block <- getFromNamespace("TableBlock", "teal.reporter")$new()
+    #' block$set_content(iris)
+    #'
     set_content = function(content) {
       checkmate::assert_multi_class(content, private$supported_tables)
       content <- to_flextable(content)