Merge branch 'dev' into ndefries/hosp-state-take_as_of

Author: nmdefries

.github/workflows/pkgdown.yaml

@@ -5,9 +5,9 @@
 # update the documentation web site on pushes to `dev` branch.
 on:
   push:
-    branches: [dev]
+    branches: [main, dev]
   pull_request:
-    branches: [dev]
+    branches: [main, dev]
   release:
     types: [published]
   workflow_dispatch:

DESCRIPTION

@@ -1,9 +1,9 @@
 Package: epidatr
 Type: Package
 Title: Client for Delphi's 'Epidata' API
-Version: 1.1.0
+Version: 1.1.0.9000
 Date: 2023-09-11
-Authors@R: 
+Authors@R:
   c(
     person("Logan", "Brooks", email = "lcbrooks@andrew.cmu.edu", role = c("aut")),
     person("Dmitry", "Shemetov", email = "dshemeto@andrew.cmu.edu", role = c("aut")),
@@ -37,6 +37,7 @@ Imports:
     openssl,
     readr,
     tibble,
+    usethis,
     xml2
 RoxygenNote: 7.2.3
 Suggests:
@@ -50,7 +51,7 @@ Suggests:
 VignetteBuilder: knitr
 Language: en-US
 Config/testthat/edition: 3
-Collate: 
+Collate:
     'auth.R'
     'avail_endpoints.R'
     'cache.R'

DEVELOPMENT.md

@@ -1,19 +1,52 @@
-## Development Environment
-
-Relevant R commands
+## Setting up the development environment
 
 ```r
 install.packages(c('devtools', 'pkgdown', 'styler', 'lintr')) # install dev dependencies
 devtools::install_deps(dependencies = TRUE) # install package dependencies
 devtools::document() # generate package meta data and man files
 devtools::build() # build package
+
+```
+
+## Validating the package
+
+```r
 styler::style_pkg() # format code
-lintr::lint_package() # lint package
+lintr::lint_package() # lint code
+
 devtools::test() # test package
 devtools::check() # check package for errors
 ```
 
-## Release Process
+## Developing the documentation site
+
+The [documentation site](https://cmu-delphi.github.io/epidatr/) is built off of the `main` branch. The `dev` version of the site is available at https://cmu-delphi.github.io/epidatr/dev.
+
+The documentation site can be previewed locally by running in R
+
+```r
+pkgdown::build_site(preview=TRUE)
+```
+
+The `main` version is available at `file:///<local path>/epidatr/docs/index.html` and `dev` at `file:///<local path>/epidatr/docs/dev/index.html`.
+
+You can also build the docs manually and launch the site with python. From the terminal, this looks like
+```bash
+R -e 'devtools::document()'
+python -m http.server -d docs
+```
+
+For `pkgdown` to correctly generate both public (`main`) and `dev` documentation sites, the package version in `DESCRIPTION` on `dev` must have four components, and be of the format `x.x.x.9000`. The package version on `main` must be in the format `x.x.x`.
+
+The documentation website is updated on push or pull request to the `main` and `dev` branches.
+
+## Release process
+
+### Manual
+
+TBD
+
+### Automated (currently unavailable)
 
 The release consists of multiple steps which can be all done via the GitHub website:
 
@@ -25,8 +58,3 @@ The release consists of multiple steps which can be all done via the GitHub webs
    2. create another [Pull Request](https://github.com/cmu-delphi/epidatr/pulls) to merge the changes back to the `dev` branch
    3. create a [GitHub release](https://github.com/cmu-delphi/epidatr/releases) with automatically derived release notes
 5. Release to CRAN
-
-[mit-image]: https://img.shields.io/badge/License-MIT-yellow.svg
-[mit-url]: https://opensource.org/license/MIT
-[github-actions-image]: https://github.com/cmu-delphi/epidatr/workflows/ci/badge.svg
-[github-actions-url]: https://github.com/cmu-delphi/epidatr/actions

NAMESPACE

@@ -44,7 +44,7 @@ export(pvt_norostat)
 export(pvt_quidel)
 export(pvt_sensors)
 export(pvt_twitter)
-export(set_api_key)
+export(save_api_key)
 export(set_cache)
 import(cachem)
 import(glue)

NEWS.md

@@ -1,6 +1,7 @@
 # epidatr 1.1.0
+
 - renamed the mostly internal `get_auth_key` to `get_api_key`
-- added `set_api_key` to more easily set the option
+- added `save_api_key` to more easily set the option
 - various CRAN submission related doc-fixes
 - fixed some errors from passing "" as a key
 

R/auth.R

@@ -10,43 +10,28 @@
 #' please consider [registering for an API
 #' key](https://api.delphi.cmu.edu/epidata/admin/registration_form).
 #'
-#' API keys are strings and can be set in two ways. If the environment variable
-#' `DELPHI_EPIDATA_KEY` is set, it will be used automatically. Environment
-#' variables can be set either in the shell or by editing your `.Renviron` file,
-#' which will ensure the setting applies to all R sessions. See `?Startup` for a
-#' description of `Renviron` files and where they can be placed.
-#'
-#' Alternately, the API key can be set from within a session by using
-#' `set_api_key()`, which sets the R option `delphi.epidata.key` using
-#' `options()`. If this option is set, it is used in preference to the
-#' environment variable, so you may change keys within an R session. R options
-#' are not preserved between sessions, so `set_api_key()` must be run every time
-#' you open R. Alternately, you can have R set the option at startup by adding
-#' it to your `.Rprofile`; see `?Startup` for a description of `Rprofile` files
-#' and where they can be placed.
+#' API keys are strings read from the environment variable `DELPHI_EPIDATA_KEY`.
+#' We recommend setting your key with `save_api_key()`, which will modify an
+#' applicable `.Renviron` file, which will be read in automatically when you
+#' start future R sessions (see [`?Startup`][base::Startup] for details on
+#' `.Renviron` files). Alternatively, you can modify the environment variable at
+#' the command line before/while launching R, or inside an R session with
+#' [`Sys.setenv()`], but these will not persist across sessions.
 #'
 #' Once an API key is set, it is automatically used for all requests made by
 #' functions in this package.
 #'
 #' @return For `get_api_key()`, returns the current API key as a string, or
 #'   `""` if none is set.
 #'
-#' @seealso [usethis::edit_r_environ()] to automatically edit the `.Renviron`
-#'   file; [usethis::edit_r_profile()] to automatically edit the `.Rprofile`
-#'   file
-#'
-#' @references Delphi Epidata API Keys documentation.
-#'   <https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html>
+#' @references
+#' - [Delphi Epidata API Keys
+#'   documentation](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html).
+#' - [Delphi Epidata API Registration
+#'   Form](https://api.delphi.cmu.edu/epidata/admin/registration_form).
 #'
-#' Delphi Epidata API Registration Form.
-#' <https://api.delphi.cmu.edu/epidata/admin/registration_form>
 #' @export
 get_api_key <- function() {
-  key <- getOption("delphi.epidata.key", default = "")
-  if (key != "") {
-    return(key)
-  }
-
   key <- Sys.getenv("DELPHI_EPIDATA_KEY", unset = "")
   if (key != "") {
     return(key)
@@ -55,7 +40,7 @@ get_api_key <- function() {
   cli::cli_warn(
     c(
       "No API key found. You will be limited to non-complex queries and encounter rate limits if you proceed.",
-      "i" = "See {.help set_api_key} for details on obtaining and setting API keys."
+      "i" = "See {.help save_api_key} for details on obtaining and setting API keys."
     ),
     .frequency = "regularly",
     .frequency_id = "delphi.epidata.key"
@@ -64,8 +49,29 @@ get_api_key <- function() {
 }
 
 #' @rdname get_api_key
-#' @param key API key to use for future requests
 #' @export
-set_api_key <- function(key) {
-  options(delphi.epidata.key = key)
+save_api_key <- function() {
+  cli::cli_inform(
+    c(
+      "i" = "This function will open your {.code .Renviron} file in a text editor. You will need to
+      write {.code DELPHI_EPIDATA_KEY=yourkeyhere} (without quotes) in the file and save it. If the editor
+      does not open, you will need to edit the file manually.",
+      "i" = "Press enter to continue."
+    )
+  )
+  readline()
+
+  if (file.exists(usethis::proj_path(".Renviron"))) {
+    usethis::edit_r_environ(scope = "project")
+
+    cat("\n\n")
+    cli::cli_inform(
+      c(
+        "i" = "Your project {.code .Renviron} file has been updated. Make sure not to share this
+        file (add it to .gitignore or equivalents)."
+      )
+    )
+  } else {
+    usethis::edit_r_environ(scope = "user")
+  }
 }

R/avail_endpoints.R

@@ -22,5 +22,6 @@ avail_endpoints <- function() {
     Endpoint = paste0(h$Name, "()"),
     Description = h$Title
   )
+  cli::cli_inform(c("i" = "Data is available for the US only, unless otherwise specified"))
   tib %>% print(n = 50)
 }

R/covidcast.R

@@ -127,7 +127,7 @@ print.covidcast_data_source <- function(x, ...) {
 #' ```
 #'
 #' These objects can be used directly to fetch data, without requiring us to use
-#' the `covidcast()` function. Simply use the `$call` attribute of the object:
+#' the `pub_covidcast()` function. Simply use the `$call` attribute of the object:
 #'
 #' ```{r}
 #' epidata$signals$`fb-survey:smoothed_cli`$call("state", "pa",