More docs, rc_list_local_tokens

NAMESPACE

@@ -30,6 +30,7 @@ export(list_validated_emails)
 export(local_check_linux)
 export(local_check_linux_images)
 export(platforms)
+export(rc_list_local_tokens)
 export(rc_list_repos)
 export(rc_new_token)
 export(rc_submit)

R/rc.R

@@ -5,12 +5,12 @@
 #' Request a new token for submissions to the R Consortium runners
 #'
 #' To build and check R packages on the RC runners of R-hub, you'll need
-#' to validate your email address. R-hub will send a token to your email
+#' to verify your email address. R-hub will send a token to your email
 #' address, and this token will be stored on your computer.
 #'
-#' You need to validate your email on each computer you want to submit
+#' You need to store a token on every computer you want to submit
 #' jobs from, either using the same token from the email you got, or
-#' you can request another token for the new machine. Your old token
+#' you can request additional tokens for the new machines. Your old token
 #' will stay valid as well.
 #'
 #' If you already have a token from a previous version of R-hub, you can
@@ -20,13 +20,14 @@
 #' ```
 #' rhub:::email_file()
 #' ```
-#' to see the file rhub uses to store your validated tokens.
+#' to see the file rhub uses to store your tokens.
 #'
-#' @param email Email address to validate. We try to detect this, but
+#' @param email Email address to verify We try to detect this, but
 #'   if the detection fails, you can specify it explicitly.
-#' @param token Token to add to the list of validated tokens.
 #'   If this argument is missing (or `NULL`), then you can specify it
 #'   interactively.
+#' @param token Token to add. If you already received a token in an email
+#'   from R-hub, you can specify that here.
 #'
 #' @export
 #' @family RC runners API
@@ -45,6 +46,19 @@ rc_new_token <- function(email = NULL, token = NULL) {
   invisible()
 }
 
+# -------------------------------------------------------------------------
+#' Show your tokens for the R Consortium runners
+#'
+#' Lists all tokens stored on the local machine.
+#'
+#' @return Data frame with string columns `email` and `token`.
+#' @export
+#' @family RC runners API
+
+rc_list_local_tokens <- function() {
+  list_validated_emails2(message = FALSE, msg_if_empty = FALSE)
+}
+
 # -------------------------------------------------------------------------
 #' List your repositories created by the R Consortium runners
 #'
@@ -96,6 +110,7 @@ rc_list_repos <- function(email = NULL) {
 #'
 #' @export
 #' @family RC runners API
+#' @seealso [rhub_platforms()] for a list of supported platforms.
 
 rc_submit <- function(path = ".", platforms = NULL, email = NULL) {
   pkg_name <- desc::desc_get("Package", file = path)[[1]]

README.Rmd

@@ -57,6 +57,9 @@ pak::pkg_install("rhub")
   You can use the [gitcreds package](https://gitcreds.r-lib.org/) to add
   the token to the git credential store.
 
+See the [R Consortium runners](#the-r-consortium-runners) section for
+using rhub if your package is not on GitHub.
+
 ### Private repositories
 
 rhub uses GitHub Actions, which is free for public repositories.
@@ -103,6 +106,50 @@ Run `rhub::rhub_check()` to start R-hub v2 checks on GitHub Actions:
 rhub::rhub_check()
 ```
 
+## The R Consortium runners
+
+If you don't want to put your package on GitHub, you can still use the
+rhub package to run package checks on any supported platform using a
+shared pool of runners in the https://github.com/r-hub2 GitHub
+organization.
+
+The process is similar to the first version of R-hub:
+
+* Set your working directory to the R package you want to check.
+* Obtain a token from R-hub, to verify your email address:
+  ```
+  rc_new_token()
+  ```
+  (You do not need to do this, if you already submitted packages to a
+  previous version of R-hub from the same machine, using the same email
+  address. Call `rc_list_local_tokens()` to check if you already have
+  tokens.)
+* Submit a build with
+  ```
+  rc_submit()
+  ```
+* Select the platforms you want to use, and follow the instructions and
+  the link provided to see your check results.
+
+### Limitations of the R Consortium runners
+
+* You package will be public for the world, and will be stored in the
+  https://github.com/r-hub2 organization. Your check output and results
+  will be public for anyone with a GitHub account. If you want to keep
+  your package private, you can put it in a private GitHub repository,
+  and use the `rhub_setup()` and `rhub_check()` functions instead.
+* The R Consortium runners are shared among all users, so you might need
+  to wait for your builds to start.
+* You have to wait at least five minutes between submissions with
+  `rc_submit()`.
+* Currently you need to create a GitHub account to see the check logs of
+  your package. You don't need a GitHub account to submit the checks.
+
+To avoid these limitations (except for the neeed for a GitHub accounr),
+put your package in a GitHub repository, and use the `rhub_setup()` and
+`rhub_check()` functions instead of `rc_submit()` and the R Consortium
+runners.
+
 ## Code of Conduct
 
 Please note that the rhub package is released with a