From 280f6084b12126c3c83ad70685bae3cb76c89204 Mon Sep 17 00:00:00 2001 From: Candace Savonen Date: Fri, 13 Dec 2024 13:54:13 -0500 Subject: [PATCH] Update docs --- man/app_set_up.Rd | 14 +++++++++++++ man/auth_from_secret.Rd | 39 +++++++++++++++++++++++++++---------- man/authorize.Rd | 17 ++++++++++------ man/cache_secrets_folder.Rd | 21 ++++++++++++++++++++ man/check_git_repo.Rd | 6 ++++-- man/course_to_book_txt.Rd | 2 +- man/delete_creds.Rd | 23 ++++++++++++++++++++++ man/get_git_auth.Rd | 28 -------------------------- man/get_github.Rd | 19 ++++++++++++++++++ man/get_pages_url.Rd | 8 +++----- man/get_repo_info.Rd | 5 +++-- man/make_screenshots.Rd | 8 ++++---- man/qrmd_files.Rd | 17 ++++++++++++++++ man/supported_endpoints.Rd | 11 +++++++++++ 14 files changed, 160 insertions(+), 58 deletions(-) create mode 100644 man/app_set_up.Rd create mode 100644 man/cache_secrets_folder.Rd create mode 100644 man/delete_creds.Rd delete mode 100644 man/get_git_auth.Rd create mode 100644 man/get_github.Rd create mode 100644 man/qrmd_files.Rd create mode 100644 man/supported_endpoints.Rd diff --git a/man/app_set_up.Rd b/man/app_set_up.Rd new file mode 100644 index 00000000..7ec332c1 --- /dev/null +++ b/man/app_set_up.Rd @@ -0,0 +1,14 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/auth.R +\name{app_set_up} +\alias{app_set_up} +\title{App Set Up} +\usage{ +app_set_up(app_name = "google") +} +\arguments{ +\item{app_name}{app would you like to authorize? Supported apps are 'google' 'calendly' and 'github'} +} +\description{ +This is a function that sets up the app. It's generally called by another function +} diff --git a/man/auth_from_secret.Rd b/man/auth_from_secret.Rd index e99bbc64..2c9960bf 100644 --- a/man/auth_from_secret.Rd +++ b/man/auth_from_secret.Rd @@ -2,30 +2,49 @@ % Please edit documentation in R/auth.R \name{auth_from_secret} \alias{auth_from_secret} -\title{Use secrets to authorize R package to access Google Slides API} +\title{Use secrets to authorize R package to access endpoints} \usage{ -auth_from_secret(access_token = NULL, refresh_token = NULL) +auth_from_secret( + app_name, + token, + access_token, + refresh_token, + cache = FALSE, + in_test = FALSE +) } \arguments{ -\item{access_token}{Access token can be obtained from running authorize() interactively: token <-authorize(); token$credentials$access_token} +\item{app_name}{Which app are you trying to authorize? 'google', 'calendly' or 'github'?} + +\item{token}{For calendly or github, pass in the API key or Personal Access Token that you have set up from going to https://github.com/settings/tokens/new or https://calendly.com/integrations/api_webhooks respectively.} + +\item{access_token}{For Google, access token can be obtained from running authorize interactively: token <-authorize(); token$credentials$access_token} + +\item{refresh_token}{For Google, refresh token can be obtained from running authorize interactively: token <-authorize(); token$credentials$refresh_token} + +\item{cache}{Should the credentials be cached? TRUE or FALSE?} -\item{refresh_token}{Refresh token can be obtained from running authorize() interactively: token <-authorize(); token$credentials$refresh_token} +\item{in_test}{If setting up auth in a test, set to TRUE so that way the authorization doesn't stick} } \value{ -OAuth token saved to the environment so the package can use the users' Google data +OAuth token saved to the environment so the package access the API data } \description{ -This is a function to authorize the R package to access the Google Slides API. If no -client.id and client.secret is provided, the package would provide predefined values. +This is a function to authorize ottrpal to access calendly, github or google noninteractively from passing in a keys or tokens. } \examples{ \dontrun{ -token <- authorize() +# Example for GitHub +# You go to https://github.com/settings/tokens/new to get a Personal Access Token +auth_from_secret("github", token = "ghp_a_github_pat_here") +# Example for authorizing for Google +token <- authorize("google") auth_from_secret( - token$credentials$access_token, - token$credentials$refresh_token + app_name = "google", + access_token = token$credentials$access_token, + refresh_token = token$credentials$refresh_token ) } diff --git a/man/authorize.Rd b/man/authorize.Rd index f26d32f9..89799f4f 100644 --- a/man/authorize.Rd +++ b/man/authorize.Rd @@ -2,26 +2,31 @@ % Please edit documentation in R/auth.R \name{authorize} \alias{authorize} -\title{Authorize R package to access the Google Slides API} +\title{Authorize R package to access endpoints} \usage{ -authorize(token = NULL, cache = FALSE, ...) +authorize(app_name = NULL, cache = FALSE, ...) } \arguments{ -\item{token}{An output from \code{\link{oauth2.0_token}} to set as the authentication token.} +\item{app_name}{app would you like to authorize? Supported apps are 'google' 'calendly' and 'github'} -\item{cache}{Should the token be cached as an .httr-oauth file?} +\item{cache}{Should the token be cached as an .httr-oauth file or API keys stored as global options?} \item{...}{Additional arguments to send to \code{\link{oauth2.0_token}}} } \value{ -OAuth token saved to the environment so the package can use the users' Google data +API token saved to the environment or the cache so it can be grabbed by functions } \description{ -This is a function to authorize the R package to access the Google Slides API interactively. +This is a function to authorize the R package to access APIs interactively. To learn more about the privacy policy for ottrpal [read here](https://www.ottrproject.org/privacypolicy.html) } \examples{ \dontrun{ authorize() + +authorize("github") + +authorize("google") + } } diff --git a/man/cache_secrets_folder.Rd b/man/cache_secrets_folder.Rd new file mode 100644 index 00000000..5679b29c --- /dev/null +++ b/man/cache_secrets_folder.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/token-handlers.R +\name{cache_secrets_folder} +\alias{cache_secrets_folder} +\title{See where your cached secrets are being stored} +\usage{ +cache_secrets_folder() +} +\value{ +an file path that shows where your cached secrets are stored +} +\description{ +This is a function to retrieve the file path of where your cached secrets are stored +} +\examples{ +\dontrun{ + +# You can see where your cached secrets are being stored by running: +cached_secrets_folder() +} +} diff --git a/man/check_git_repo.Rd b/man/check_git_repo.Rd index 83278d48..d2431ed1 100644 --- a/man/check_git_repo.Rd +++ b/man/check_git_repo.Rd @@ -6,7 +6,7 @@ \usage{ check_git_repo( repo_name, - git_pat = NULL, + token = NULL, silent = TRUE, return_repo = FALSE, verbose = TRUE @@ -15,7 +15,7 @@ check_git_repo( \arguments{ \item{repo_name}{the name of the repository, e.g. jhudsl/OTTR_Template} -\item{git_pat}{A personal access token from GitHub. Only necessary if the +\item{token}{A personal access token from GitHub. Only necessary if the repository being checked is a private repository.} \item{silent}{TRUE/FALSE of whether the warning from the git ls-remote @@ -36,4 +36,6 @@ Given a repository name, check with git ls-remote whether the repository exists \examples{ check_git_repo("jhudsl/OTTR_Template") + + } diff --git a/man/course_to_book_txt.Rd b/man/course_to_book_txt.Rd index 49bfd0b9..6e53fb57 100644 --- a/man/course_to_book_txt.Rd +++ b/man/course_to_book_txt.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/leanpub.R +% Please edit documentation in R/book_txt.R \name{course_to_book_txt} \alias{course_to_book_txt} \title{Create Book.txt file from files existing in quiz directory} diff --git a/man/delete_creds.Rd b/man/delete_creds.Rd new file mode 100644 index 00000000..9f276c9e --- /dev/null +++ b/man/delete_creds.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/auth.R +\name{delete_creds} +\alias{delete_creds} +\title{Delete cached ottrpal credentials} +\usage{ +delete_creds(app_name = "all") +} +\arguments{ +\item{app_name}{which app would you like to delete the creds for? Default is to delete the creds for all.} +} +\value{ +Cached credentials are deleted and report is given back +} +\description{ +This is a function to delete cached creds and creds in the current environment that were set by ottrpal +} +\examples{ +\dontrun{ + +delete_creds("google") +} +} diff --git a/man/get_git_auth.Rd b/man/get_git_auth.Rd deleted file mode 100644 index c5662905..00000000 --- a/man/get_git_auth.Rd +++ /dev/null @@ -1,28 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/github_handling.R -\name{get_git_auth} -\alias{get_git_auth} -\title{Handle GitHub PAT authorization} -\usage{ -get_git_auth( - git_pat = NULL, - git_username = "PersonalAccessToken", - quiet = FALSE -) -} -\arguments{ -\item{git_pat}{If private repositories are to be retrieved, a github personal -access token needs to be supplied. If none is supplied, then this will attempt to -grab from a git pat set in the environment with usethis::create_github_token().} - -\item{git_username}{Optional, can include username for credentials.} - -\item{quiet}{Use TRUE if you don't want the warning about no GitHub credentials.} -} -\value{ -Authorization argument to supply to curl OR a blank string if no -authorization is found or supplied. -} -\description{ -Handle things whether or not a GitHub PAT is supplied. -} diff --git a/man/get_github.Rd b/man/get_github.Rd new file mode 100644 index 00000000..a1573c2c --- /dev/null +++ b/man/get_github.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/github_handling.R +\name{get_github} +\alias{get_github} +\title{Handler function for GET requests from GitHub} +\usage{ +get_github(token = NULL, url) +} +\arguments{ +\item{token}{You can provide the Personal Access Token key directly or this function will attempt to grab a PAT that was stored using the `authorize("github")` function} + +\item{url}{What is the URL endpoint we are attempting to grab here?} +} +\value{ +Information regarding a Github account +} +\description{ +This is a function to get the GitHub user's info +} diff --git a/man/get_pages_url.Rd b/man/get_pages_url.Rd index 40b34963..2401c1ab 100644 --- a/man/get_pages_url.Rd +++ b/man/get_pages_url.Rd @@ -4,16 +4,14 @@ \alias{get_pages_url} \title{Retrieve pages url for a repo} \usage{ -get_pages_url(repo_name, git_pat = NULL, verbose = FALSE, keep_json = FALSE) +get_pages_url(repo_name, token = NULL, verbose = FALSE, keep_json = FALSE) } \arguments{ \item{repo_name}{The full name of the repo to get bookdown chapters from. e.g. "jhudsl/OTTR_Template"} -\item{git_pat}{If private repositories are to be retrieved, a github personal -access token needs to be supplied. If none is supplied, then this will attempt to -grab from a git pat set in the environment with usethis::create_github_token(). -Authorization handled by \link[cow]{get_git_auth}} +\item{token}{If private repositories are to be retrieved, a github personal +access token needs to be supplied. Run `authorize("github")` to set this.} \item{verbose}{TRUE/FALSE do you want more progress messages?} diff --git a/man/get_repo_info.Rd b/man/get_repo_info.Rd index cd7ae486..5178bba6 100644 --- a/man/get_repo_info.Rd +++ b/man/get_repo_info.Rd @@ -4,13 +4,13 @@ \alias{get_repo_info} \title{Retrieve information about a github repo} \usage{ -get_repo_info(repo_name, git_pat = NULL, verbose = FALSE) +get_repo_info(repo_name, token = NULL, verbose = FALSE) } \arguments{ \item{repo_name}{The full name of the repo to get bookdown chapters from. e.g. "jhudsl/OTTR_Template"} -\item{git_pat}{If private repositories are to be retrieved, a github personal +\item{token}{If private repositories are to be retrieved, a github personal access token needs to be supplied. If none is supplied, then this will attempt to grab from a git pat set in the environment with usethis::create_github_token(). Authorization handled by \link[githubr]{get_git_auth}} @@ -28,4 +28,5 @@ GitHub API and read it into R. \examples{ repo_info <- get_repo_info("jhudsl/Documentation_and_Usability") + } diff --git a/man/make_screenshots.Rd b/man/make_screenshots.Rd index 6dcb0b2a..fbe274e3 100644 --- a/man/make_screenshots.Rd +++ b/man/make_screenshots.Rd @@ -6,7 +6,7 @@ \usage{ make_screenshots( path = ".", - git_pat, + token, repo, output_dir = file.path(path, "resources", "chapt_screen_images"), base_url = NULL @@ -15,13 +15,13 @@ make_screenshots( \arguments{ \item{path}{default is to look for OTTR files in current directory based on existence of .github. But if you'd like to run this in a different path, you can point to that file path.} -\item{git_pat}{required argument; a Git secret -- see https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens for more info} +\item{token}{required argument; a Git secret -- see https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens for more info} \item{repo}{required argument; GitHub repository name, e.g., jhudsl/OTTR_Template} \item{output_dir}{default is "resources/chapt_screen_images"; Output directory where the chapter's screen images should be stored. For OTTR courses, don't change this unless you've changed the downstream functions accordingly.} -\item{base_url}{default is NULL; rendered bookdown URL where screenshots are taken from, if NULL, the function will use the repo_name and and git_pat to find the base_url} +\item{base_url}{default is NULL; rendered bookdown URL where screenshots are taken from, if NULL, the function will use the repo_name and and token to find the base_url} } \value{ the file path for file where chapter urls are saved @@ -33,7 +33,7 @@ This function creates screenshots of course chapters that are stored in a create \dontrun{ make_screenshots( - git_pat = Sys.getenv("secrets.GH_PAT"), + token = Sys.getenv("secrets.GH_PAT"), repo = "jhudsl/OTTR_Template" ) } diff --git a/man/qrmd_files.Rd b/man/qrmd_files.Rd new file mode 100644 index 00000000..422a1b71 --- /dev/null +++ b/man/qrmd_files.Rd @@ -0,0 +1,17 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/book_txt.R +\name{qrmd_files} +\alias{qrmd_files} +\title{Get file paths to all qmds or rmds in the course website directory} +\usage{ +qrmd_files(path = ".") +} +\arguments{ +\item{path}{Where to look for the _bookdown.yml or _quarto.yml file. Passes to get_yaml_spec() function. By default looks in current directory} +} +\value{ +The file paths to rmds or wmds listed in the _bookdown.yml or _quarto.yml file. +} +\description{ +Get file paths to all qmds or rmds in the course website directory +} diff --git a/man/supported_endpoints.Rd b/man/supported_endpoints.Rd new file mode 100644 index 00000000..7a74d439 --- /dev/null +++ b/man/supported_endpoints.Rd @@ -0,0 +1,11 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/token-handlers.R +\name{supported_endpoints} +\alias{supported_endpoints} +\title{Supported endpoints} +\usage{ +supported_endpoints() +} +\description{ +This is function stores endpoints and supported app names +}