From 9adfe6294ac0dd5ba2ffd5dbd012161bd9d51fe6 Mon Sep 17 00:00:00 2001 From: Lorenz Walthert Date: Sat, 23 Jan 2021 00:44:59 +0100 Subject: [PATCH 1/4] improve the caching docs --- R/ui-caching.R | 48 ++++++++++++++++++++++++-------------------- inst/WORDLIST | 2 ++ man/caching.Rd | 54 +++++++++++++++++++++++++++++--------------------- 3 files changed, 60 insertions(+), 44 deletions(-) diff --git a/R/ui-caching.R b/R/ui-caching.R index 585b0b04c..c3033a0b9 100644 --- a/R/ui-caching.R +++ b/R/ui-caching.R @@ -28,38 +28,44 @@ cache_clear <- function(cache_name = NULL, ask = TRUE) { #' Code is cached by expression and the cache is shared across all APIs (e.g. #' `style_text()` and Addin). #' -#' @section Setup: -#' styler by default uses caching via the `{R.cache}` package. You will be -#' asked to let it create a permanent cache on your file system that styler -#' will use in case it is not set already up for another tool that -#' uses `{R.cache}`. We encourage users to let `{R.cache}` create a permanent -#' directory for caching because, otherwise, the cache is lost at restart of R. +#' @section Manage the cache: +#' See [cache_info()],[cache_deactivate()] or [cache_clear()] for utilities to +#' manage the cache. You can deactivate it altogether with [cache_activate()]. +#' Since we leverage `{R.cache}` to manage the cache, you can also use any +#' `{R.cache}` functionality to manipulate it. +#' +#' @section Interactive setup: +#' styler by default uses caching via the `{R.cache}` package. When interacting +#' with `{styler}`, you will be asked to let it create a permanent cache on your +#' file system that styler will use in case it is not set already up for another +#' tool that uses `{R.cache}`. We encourage users to let `{R.cache}` create a +#' permanent directory for caching because, otherwise, the cache is lost at +#' restart of R. +#' +#' @section Non-interactive setup: +#' In some cases, you want to avoid the interactive prompt described above. In +#' that situation, use `R.cache::setCacheRootPath("/path/to/cache")` to an +#' existent directory and set the R option `R.cache.rootPath` or the environment +#' variable `R_CACHE_ROOTPATH` to this path before you call the styler API. This +#' should avoid the prompt. #' #' @section Non-interactive use: #' Note that if you have never authorized `{R.cache}` to create the cache in a -#' permanent directory, it will build the cache in a temporary directory. To -#' create a permanent cache, just open an interactive R session and type -#' `cache_info()`. You can see under `Location:` if a permanent directory is -#' used and if not, `{R.cache}` will ask you to create one the first time you -#' use `{R.cache}` in an R session. +#' permanent directory and you use styler non-interactively, it will build the +#' cache in a temporary directory. To create a permanent cache, follow the +#' section 'Non-interactive setup' or 'Interactive setup' above. #' #' @section Invalidation: #' The cache is specific to a version of styler by default, because different #' versions potentially format code differently. This means after upgrading #' styler or a style guide you use, the cache will be re-built. #' -#' @section Manage the cache: -#' See [cache_info()], -#' [cache_activate()], [cache_clear()] for utilities to manage the cache. Since -#' we leverage `{R.cache}` to manage the cache, you can also use any `{R.cache}` -#' functionality to manipulate it. -#' #' @section Using a cache for styler in CI/CD: #' If you want to set up caching in a CI/CD pipeline, we suggest to set the -#' `{R.cache}` root path to a directory for which you have the cache enabled. -#' The former can be done with `R.cache::setCacheRootPath("/path/to/cache")`, -#' the latter can often be set in config files of CI/CD tools, e.g. see the -#' the [Travis documentation on caching](https://docs.travis-ci.com/user/caching). +#' `{R.cache}` root path to a directory for which you have the cache enabled as +#' described above in the section 'Non-interactive setup'. This can often be set +#' in config files of CI/CD tools, e.g. see the +#' [Travis documentation on caching](https://docs.travis-ci.com/user/caching). #' #' @name caching NULL diff --git a/inst/WORDLIST b/inst/WORDLIST index 23cda16a8..ab4a2eb79 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -143,6 +143,8 @@ rnw Rnw roclet roclets +rootPath +ROOTPATH roundtrip roxgen roxygen diff --git a/man/caching.Rd b/man/caching.Rd index 6e8838d24..0b900b4c2 100644 --- a/man/caching.Rd +++ b/man/caching.Rd @@ -10,23 +10,39 @@ style guide and you have previously styled that code, it will be quicker. Code is cached by expression and the cache is shared across all APIs (e.g. \code{style_text()} and Addin). } -\section{Setup}{ +\section{Manage the cache}{ + +See \code{\link[=cache_info]{cache_info()}},\code{\link[=cache_deactivate]{cache_deactivate()}} or \code{\link[=cache_clear]{cache_clear()}} for utilities to +manage the cache. You can deactivate it altogether with \code{\link[=cache_activate]{cache_activate()}}. +Since we leverage \code{{R.cache}} to manage the cache, you can also use any +\code{{R.cache}} functionality to manipulate it. +} -styler by default uses caching via the \code{{R.cache}} package. You will be -asked to let it create a permanent cache on your file system that styler -will use in case it is not set already up for another tool that -uses \code{{R.cache}}. We encourage users to let \code{{R.cache}} create a permanent -directory for caching because, otherwise, the cache is lost at restart of R. +\section{Interactive setup}{ + +styler by default uses caching via the \code{{R.cache}} package. When interacting +with \code{{styler}}, you will be asked to let it create a permanent cache on your +file system that styler will use in case it is not set already up for another +tool that uses \code{{R.cache}}. We encourage users to let \code{{R.cache}} create a +permanent directory for caching because, otherwise, the cache is lost at +restart of R. +} + +\section{Non-interactive setup}{ + +In some cases, you want to avoid the interactive prompt described above. In +that situation, use \code{R.cache::setCacheRootPath("/path/to/cache")} to an +existent directory and set the R option \code{R.cache.rootPath} or the environment +variable \code{R_CACHE_ROOTPATH} to this path before you call the styler API. This +should avoid the prompt. } \section{Non-interactive use}{ Note that if you have never authorized \code{{R.cache}} to create the cache in a -permanent directory, it will build the cache in a temporary directory. To -create a permanent cache, just open an interactive R session and type -\code{cache_info()}. You can see under \verb{Location:} if a permanent directory is -used and if not, \code{{R.cache}} will ask you to create one the first time you -use \code{{R.cache}} in an R session. +permanent directory and you use styler non-interactively, it will build the +cache in a temporary directory. To create a permanent cache, follow the +section 'Non-interactive setup' or 'Interactive setup' above. } \section{Invalidation}{ @@ -36,20 +52,12 @@ versions potentially format code differently. This means after upgrading styler or a style guide you use, the cache will be re-built. } -\section{Manage the cache}{ - -See \code{\link[=cache_info]{cache_info()}}, -\code{\link[=cache_activate]{cache_activate()}}, \code{\link[=cache_clear]{cache_clear()}} for utilities to manage the cache. Since -we leverage \code{{R.cache}} to manage the cache, you can also use any \code{{R.cache}} -functionality to manipulate it. -} - \section{Using a cache for styler in CI/CD}{ If you want to set up caching in a CI/CD pipeline, we suggest to set the -\code{{R.cache}} root path to a directory for which you have the cache enabled. -The former can be done with \code{R.cache::setCacheRootPath("/path/to/cache")}, -the latter can often be set in config files of CI/CD tools, e.g. see the -the \href{https://docs.travis-ci.com/user/caching}{Travis documentation on caching}. +\code{{R.cache}} root path to a directory for which you have the cache enabled as +described above in the section 'Non-interactive setup'. This can often be set +in config files of CI/CD tools, e.g. see the +\href{https://docs.travis-ci.com/user/caching}{Travis documentation on caching}. } From f14276d7f8689681f284674e4b8271f5d047bb0f Mon Sep 17 00:00:00 2001 From: Lorenz Walthert Date: Sat, 23 Jan 2021 00:51:32 +0100 Subject: [PATCH 2/4] clarify --- R/ui-caching.R | 8 ++++---- man/caching.Rd | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/R/ui-caching.R b/R/ui-caching.R index c3033a0b9..5234bb4a5 100644 --- a/R/ui-caching.R +++ b/R/ui-caching.R @@ -44,10 +44,10 @@ cache_clear <- function(cache_name = NULL, ask = TRUE) { #' #' @section Non-interactive setup: #' In some cases, you want to avoid the interactive prompt described above. In -#' that situation, use `R.cache::setCacheRootPath("/path/to/cache")` to an -#' existent directory and set the R option `R.cache.rootPath` or the environment -#' variable `R_CACHE_ROOTPATH` to this path before you call the styler API. This -#' should avoid the prompt. +#' that situation, you can set the path to the cache with +#' `R.cache::setCacheRootPath("/path/to/cache")`, the R option +#' `R.cache.rootPath` or the environment variable `R_CACHE_ROOTPATH` to an +#' existent path before you call the styler API. This should avoid the prompt. #' #' @section Non-interactive use: #' Note that if you have never authorized `{R.cache}` to create the cache in a diff --git a/man/caching.Rd b/man/caching.Rd index 0b900b4c2..6ba2be55f 100644 --- a/man/caching.Rd +++ b/man/caching.Rd @@ -31,10 +31,10 @@ restart of R. \section{Non-interactive setup}{ In some cases, you want to avoid the interactive prompt described above. In -that situation, use \code{R.cache::setCacheRootPath("/path/to/cache")} to an -existent directory and set the R option \code{R.cache.rootPath} or the environment -variable \code{R_CACHE_ROOTPATH} to this path before you call the styler API. This -should avoid the prompt. +that situation, you can set the path to the cache with +\code{R.cache::setCacheRootPath("/path/to/cache")}, the R option +\code{R.cache.rootPath} or the environment variable \code{R_CACHE_ROOTPATH} to an +existent path before you call the styler API. This should avoid the prompt. } \section{Non-interactive use}{ From 3cfa76b2fe0eae18bde114ec662bef2d7ebb0442 Mon Sep 17 00:00:00 2001 From: Lorenz Walthert Date: Sat, 23 Jan 2021 01:03:51 +0100 Subject: [PATCH 3/4] advise against setCacheRootPath() --- R/ui-caching.R | 5 +++-- man/caching.Rd | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/R/ui-caching.R b/R/ui-caching.R index 5234bb4a5..ab2b81f8f 100644 --- a/R/ui-caching.R +++ b/R/ui-caching.R @@ -44,10 +44,11 @@ cache_clear <- function(cache_name = NULL, ask = TRUE) { #' #' @section Non-interactive setup: #' In some cases, you want to avoid the interactive prompt described above. In -#' that situation, you can set the path to the cache with -#' `R.cache::setCacheRootPath("/path/to/cache")`, the R option +#' that situation, you can set the path to the cache with the R option #' `R.cache.rootPath` or the environment variable `R_CACHE_ROOTPATH` to an #' existent path before you call the styler API. This should avoid the prompt. +#' `R.cache::setCacheRootPath("/path/to/cache")` is also programmatic but will +#' probably give the prompt anyways if called interactively. #' #' @section Non-interactive use: #' Note that if you have never authorized `{R.cache}` to create the cache in a diff --git a/man/caching.Rd b/man/caching.Rd index 6ba2be55f..86c7ceec7 100644 --- a/man/caching.Rd +++ b/man/caching.Rd @@ -31,10 +31,11 @@ restart of R. \section{Non-interactive setup}{ In some cases, you want to avoid the interactive prompt described above. In -that situation, you can set the path to the cache with -\code{R.cache::setCacheRootPath("/path/to/cache")}, the R option +that situation, you can set the path to the cache with the R option \code{R.cache.rootPath} or the environment variable \code{R_CACHE_ROOTPATH} to an existent path before you call the styler API. This should avoid the prompt. +\code{R.cache::setCacheRootPath("/path/to/cache")} is also programmatic but will +probably give the prompt anyways if called interactively. } \section{Non-interactive use}{ From 0fb8e514172e1a38e1d3106fc36d27185b37bd58 Mon Sep 17 00:00:00 2001 From: Lorenz Walthert Date: Sat, 23 Jan 2021 16:29:19 +0100 Subject: [PATCH 4/4] fix order and notation. --- R/ui-caching.R | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/R/ui-caching.R b/R/ui-caching.R index ab2b81f8f..8bd31638c 100644 --- a/R/ui-caching.R +++ b/R/ui-caching.R @@ -29,13 +29,13 @@ cache_clear <- function(cache_name = NULL, ask = TRUE) { #' `style_text()` and Addin). #' #' @section Manage the cache: -#' See [cache_info()],[cache_deactivate()] or [cache_clear()] for utilities to -#' manage the cache. You can deactivate it altogether with [cache_activate()]. +#' See [cache_info()],[cache_activate()] or [cache_clear()] for utilities to +#' manage the cache. You can deactivate it altogether with [cache_deactivate()]. #' Since we leverage `{R.cache}` to manage the cache, you can also use any #' `{R.cache}` functionality to manipulate it. #' #' @section Interactive setup: -#' styler by default uses caching via the `{R.cache}` package. When interacting +#' `{styler}` by default uses caching via the `{R.cache}` package. When interacting #' with `{styler}`, you will be asked to let it create a permanent cache on your #' file system that styler will use in case it is not set already up for another #' tool that uses `{R.cache}`. We encourage users to let `{R.cache}` create a @@ -52,7 +52,7 @@ cache_clear <- function(cache_name = NULL, ask = TRUE) { #' #' @section Non-interactive use: #' Note that if you have never authorized `{R.cache}` to create the cache in a -#' permanent directory and you use styler non-interactively, it will build the +#' permanent directory and you use `{styler}` non-interactively, it will build the #' cache in a temporary directory. To create a permanent cache, follow the #' section 'Non-interactive setup' or 'Interactive setup' above. #'