update install guide; add getting help; pkg name lowercase (#890)

- update install guide - added back install from GH as this is still a standard way of installing non-CRAN packages. I added install via `pak` and not `remotes` because this is also standard for pkgs from tidyverse or r-lib. - change urls to teal gallery and tlg-catalog - added Getting Help section with reference to slack channel - replace `browseVignettes(package = "teal")` with url as I believe that most of users will read README from within pkgdown webpage. - replace "Teal" with "teal" to keep consistent package name - UPDATE: added "Usage section" with gif recording and move all "Please refer to ... for more" under that section Please add your feedback. I would like to treat this PR as a reference to the issue for other package updates. --------- Signed-off-by: Pawel Rucki <[email protected]> Co-authored-by: Aleksander Chlebowski <[email protected]> Co-authored-by: kartikeya kirar <[email protected]>
insightsengineering · Aug 10, 2023 · 39a98f4 · 39a98f4
1 parent 32d77fc
commit 39a98f4
Show file tree

Hide file tree

Showing 10 changed files with 82 additions and 41 deletions.
diff --git a/R/module_teal.R b/R/module_teal.R
@@ -1,6 +1,6 @@
 # This module is the main teal module that puts everything together.
 
-#' Teal main app module
+#' teal main app module
 #'
 #' This is the main teal app that puts everything together.
 #'

diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# Teal: Interactive Exploratory Data Analysis with Shiny Web-Applications <a href='https://insightsengineering.github.io/teal/'><img src="man/figures/teal.png" align="right" height="139" style="max-width: 100%;"/></a  >
+# `teal`: Interactive Exploratory Data Analysis with Shiny Web-Applications <a href='https://insightsengineering.github.io/teal/'><img src="man/figures/teal.png" align="right" height="139" style="max-width: 100%;"/></a  >
 
 <!-- start badges -->
 [![Check 🛠](https://github.com/insightsengineering/teal/actions/workflows/check.yaml/badge.svg)](https://insightsengineering.github.io/teal/main/unit-test-report/)
@@ -19,7 +19,7 @@
 [![Open Issues](https://img.shields.io/github/issues-raw/insightsengineering/teal?color=red\&label=open%20issues)](https://github.com/insightsengineering/teal/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)
 <!-- end badges -->
 
-*teal* is a shiny-based interactive exploration framework for analyzing data. `teal` applications require app developers to specify:
+`teal` is a shiny-based interactive exploration framework for analyzing data. `teal` applications require app developers to specify:
 
 <!-- markdownlint-disable MD007 MD030 -->
 -   Data, which can be:
@@ -48,23 +48,68 @@ A lot of the functionality of the `teal` framework derives from the following pa
 
 <!-- markdownlint-enable MD007 MD030 -->
 
-See these packages for more information about how to use the different parts of the `teal` framework.
+## Installation
 
-Please see [`teal` gallery](https://github.com/insightsengineering/teal.gallery) and [TLG Catalog](https://github.com/insightsengineering/tlg-catalog) to see examples of `teal` apps.
+```r
+install.packages("teal", repos = c("https://insightsengineering.r-universe.dev", getOption("repos")))
 
-## Installation
+# install.packages("pak")
+pak::pak("insightsengineering/teal@*release")
+```
 
-From July 2023 `insightsengineering` packages are available on [r-universe](https://r-universe.dev/).
+Alternatively, you might also use the development version.
 
 ```r
-# stable versions
-install.packages('teal', repos = c('https://insightsengineering.r-universe.dev', 'https://cloud.r-project.org'))
+install.packages("teal", repos = c("https://pharmaverse.r-universe.dev", getOption("repos")))
+
+# install.packages("pak")
+pak::pak("insightsengineering/teal")
+```
 
-# beta versions
-install.packages('teal', repos = c('https://pharmaverse.r-universe.dev', 'https://cloud.r-project.org'))
+## Usage
+
+```r
+library(teal)
+
+app <- init(
+  data = teal_data(
+    dataset("iris", iris)
+  ),
+  modules = list(
+    module(
+      "iris histogram",
+      server = function(input, output, session, data) {
+        output$hist <- renderPlot(
+          hist(data[["iris"]]()[[input$var]])
+        )
+      },
+      ui = function(id, data, ...) {
+        ns <- NS(id)
+        list(
+          shiny::selectInput(
+            ns("var"),
+            "Column name",
+            names(data[["iris"]]())[1:4]
+          ),
+          plotOutput(ns("hist"))
+        )
+      }
+    )
+  )
+)
+
+shinyApp(app$ui, app$server)
 ```
 
-See package vignettes `browseVignettes(package = "teal")` for usage of this package.
+![App recording](./inst/readme_app.gif)
+
+Please see [`teal` gallery](https://insightsengineering.github.io/teal.gallery) and [TLG Catalog](https://insightsengineering.github.io/tlg-catalog) to see examples of `teal` apps.
+
+Please start with the ["Getting Started" article](https://insightsengineering.github.io/teal/articles/teal.html) and then other [package vignettes](https://insightsengineering.github.io/teal/articles/index.html) for more detailed guide.
+
+## Getting help
+
+If you encounter a bug or you have a feature request - please file an issue. For questions, discussions and staying up to date, please use the "teal" channel in the [pharmaverse slack workspace](https://pharmaverse.slack.com).
 
 ## Acknowledgment
 

diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -12,10 +12,10 @@ navbar:
     reports:
       text: Reports
       menu:
-      - text: Coverage report
-        href: coverage-report/
-      - text: Unit test report
-        href: unit-test-report/
+        - text: Coverage report
+          href: coverage-report/
+        - text: Unit test report
+          href: unit-test-report/
     github:
       icon: fa-github
       href: https://github.com/insightsengineering/teal
@@ -36,7 +36,7 @@ articles:
       - teal-bs-themes
 
 reference:
-  - title: Teal Core Functions
+  - title: teal Core Functions
     desc: These are the main functions needed to build a teal app.
     contents:
       - init

diff --git a/inst/WORDLIST b/inst/WORDLIST
@@ -15,3 +15,4 @@ themer
 theming
 uncheck
 cloneable
+pharmaverse
diff --git a/inst/readme_app.gif b/inst/readme_app.gif
diff --git a/man/module_teal.Rd b/man/module_teal.Rd
diff --git a/vignettes/including-general-data-in-teal.Rmd b/vignettes/including-general-data-in-teal.Rmd
@@ -11,7 +11,7 @@ vignette: >
 
 ## Introduction
 
-Teal applications are not restricted to `CDISC`-standard data. Although many teal modules included with `NEST` are designed for `CDISC` data, those in the library `teal.modules.general` have been designed to work with non-relational data.
+`teal` applications are not restricted to `CDISC`-standard data. Although many teal modules included with `NEST` are designed for `CDISC` data, those in the library `teal.modules.general` have been designed to work with non-relational data.
 
 For example this application uses the standard `iris` and `mtcars` datasets:
 

diff --git a/vignettes/teal-bs-themes.Rmd b/vignettes/teal-bs-themes.Rmd
@@ -1,22 +1,22 @@
 ---
-title: "Teal and Bootstrap Themes"
+title: "teal and Bootstrap Themes"
 author: "NEST CoreDev"
 date: "2022-09-08"
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{Teal and Bootstrap Themes}
+  %\VignetteIndexEntry{teal and Bootstrap Themes}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---
 
 ## Introduction
 
-We offer the easy application of a custom bootstrap theme to a `teal::init` app. 
-Teal is a consumer of the `bslib` R package which provides tools for customizing Bootstrap themes e.g. of Shiny apps.
+We offer an easy application of a custom bootstrap theme to a `teal::init` app.
+`teal` is a consumer of the `bslib` R package which provides tools for customizing Bootstrap themes e.g. of Shiny apps.
 
 ## Usage
 
-Teal users have the benefit of custom bootstrap themes by specifying the `teal.bs_theme` R option, which has to be set to `bslib::bs_theme` object.
+`teal` users have the benefit of custom bootstrap themes by specifying the `teal.bs_theme` R option, which has to be set to `bslib::bs_theme` object.
 The `bslib::bs_theme(...)` function creates a Bootstrap theme object, where you should specify the (major) Bootstrap version (default or one of 3, 4 or 5).
 Optionally you could choose a **`bootswatch` theme** and **customize the app CSS** with functions like `bslib::bs_add_rules`.
 Please read more about custom themes in [the `bslib` getting started vignette](https://rstudio.github.io/bslib/articles/bslib.html).
@@ -39,7 +39,7 @@ options("teal.bs_theme" = bslib::bs_theme("Custom Options"))
 The best and recommended ways to **explore** the bootstrap themes are to use `bslib::run_with_themer(shinyApp(app$ui, app$server))` or `bslib::bs_theme_preview()`,
 both functions offer an interactive explore mode.
 Note that the interactive theming for Bootstrap 3 is not supported.
-The `bslib::bs_theme_preview()` is recommended when the end user does not have any shiny app yet. 
+The `bslib::bs_theme_preview()` is recommended when the end user does not have any shiny app yet.
 When you already have a shiny app and you want to test different bootstrap themes (and `CSS` styling) then `bslib::run_with_themer(shinyApp(app$ui, app$server))` is recommended.
 
 Available bootstrap versions could be checked with `bslib::versions()` and bootstrap themes (`bootswatch`) with `bslib::bootswatch_themes(version = "5")`.
@@ -103,7 +103,7 @@ remotes::install_github("https://github.com/dreamRs/shinyWidgets@main")
 
 ### Regular `shiny::fluidPage`
 
-If you want to update the theme in the regular `shiny::fluidPage` like app, you do not need the `teal.bs_theme` option. Then simply provide the `bslib::bs_theme` directly to the `shiny::fluidPage(theme = bslib::bs_theme(...), ...)`. 
+If you want to update the theme in the regular `shiny::fluidPage` like app, you do not need the `teal.bs_theme` option. Then simply provide the `bslib::bs_theme` directly to the `shiny::fluidPage(theme = bslib::bs_theme(...), ...)`.
 
 ### Interactive theming guide
 

diff --git a/vignettes/teal-options.Rmd b/vignettes/teal-options.Rmd
@@ -1,10 +1,10 @@
 ---
-title: "Modifying a Teal application with R options"
+title: "Modifying a teal application with R options"
 author: "Paweł Rucki"
 date: " 2021-12-23"
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{Modifying a Teal application with R options}
+  %\VignetteIndexEntry{Modifying a teal application with R options}
   %\VignetteEncoding{UTF-8}
   %\VignetteEngine{knitr::rmarkdown}
 editor_options:
@@ -81,7 +81,7 @@ This option allows modifying labels and themes of all `ggplot2` plots in a `teal
 Default: `teal.widgets::ggplot2_args()`.
 
 ### `teal.plot_dpi` (integer value 24 or larger)
-This option controls the dots per inch of the graphs rendered and downloaded when using `plot_with_settings`. 
+This option controls the dots per inch of the graphs rendered and downloaded when using `plot_with_settings`.
 
 Default: 72
 

diff --git a/vignettes/teal.Rmd b/vignettes/teal.Rmd
@@ -1,10 +1,10 @@
 ---
-title: "Getting Started with Teal"
+title: "Getting Started with teal"
 author: "NEST CoreDev"
 date: "2022-11-03"
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{Getting Started with Teal}
+  %\VignetteIndexEntry{Getting Started with teal}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---
@@ -14,7 +14,7 @@ vignette: >
 *teal* is a shiny-based interactive exploration framework for analyzing data, with particular emphasis on
 `CDISC` clinical trial data. `teal` applications provide their users with:
 
-* Ability to "pull" in data from external data sources 
+* Ability to "pull" in data from external data sources
 * Dynamic filtering of data to be used in the analyses
 * Ability to generate reproducible code to regenerate the on-screen analyses
 * Ability to create and download reports containing results of analyses (for analysis modules which support reporting)
@@ -75,17 +75,17 @@ For modules which include reproducibility functionality, it often contains a "Sh
 
 ## Creating your own applications
 
-`init` is the key function to use to create your `teal` application and it requires two key arguments: `data` and `modules`. 
+`init` is the key function to use to create your `teal` application and it requires two key arguments: `data` and `modules`.
 
-### Application Data 
+### Application Data
 
 The `data` argument to the `init` function specifies the data used by your application. This can contain data currently in your R session,
 as in the example above, but also can contain `connectors` which describe where to "pull" data from when the application is run. This can be
 used to allow data to be pulled into `teal` applications from external sources which require your application users to enter credentials.
 
 In the example above we call `teal_data` to convert the raw datasets into `teal` specific datasets and to bind them in one `R` object.
-This function can also be used to specify relationships between different datasets. 
-In order to use `CDISC` clinical trial data in a `teal` application the `cdisc_data` function is used instead.  
+This function can also be used to specify relationships between different datasets.
+In order to use `CDISC` clinical trial data in a `teal` application the `cdisc_data` function is used instead.
 
 For further details we recommend exploring the [`teal.data`](https://insightsengineering.github.io/teal.data/) package documentation.
 
@@ -110,11 +110,6 @@ so your users can view and configure their reports before downloading them.
 
 To learn more about the `teal` framework we recommend first exploring some of the available analysis modules.
 
-## Known bugs
-
-- It could be needed to use `options(shiny.useragg = FALSE)` to make the `teal::init` apps more stable, [till `ragg` package is not fixed](https://github.com/rstudio/shiny/issues/3704). It is recommended to put this option in the `.Rprofile` file.
-
-
 For example see:
 
 * [general analysis modules](https://insightsengineering.github.io/teal.modules.general/)