Package 'cow'

Borrow/link a chapter from another bookdown course

Description

If you have two courses that the content and topics overlap, you may want to share written material between the two. But, if you copy and paste to share material this would create a maintenance problem because if you update one you will need to remember to copy over the other! 😱 To borrow a chapter from another course, create an .Rmd as you normally would, with an H1 title if you wish. Then in a code chunk, use cow::borrow_chapter() to have the content from an Rmd from another repository knitted into the Rmd.

Usage

borrow_chapter(
  doc_path,
  repo_name = NULL,
  remove_h1 = FALSE,
  branch = "main",
  git_pat = NULL,
  base_url = "https://raw.githubusercontent.com",
  dest_dir = file.path("resources", "other_chapters")
)

Arguments

doc_path	A file path of markdown or R Markdown document of the chapter in the repository you are retrieving it from that you would like to include in the current document. e.g "docs/intro.md" or "intro.md"
repo_name	A character vector indicating the repo name of where you are borrowing from. e.g. "jhudsl/OTTR_Template/". For a Wiki of a repo, use "wiki/jhudsl/OTTR_Template/" If nothing is provided, will look for local file.
remove_h1	If TRUE Remove all h1 headers.
branch	Default is to pull from main branch, but need to declare if other branch is needed.
git_pat	A personal access token from GitHub. Only necessary if the repository being checked is a private repository.
base_url	it's assumed this is coming from github so it is by default 'https://raw.githubusercontent.com/'
dest_dir	A file path where the file should be stored upon arrival to the current repository.

Value

An Rmarkdown or markdown is knitted into the document from another repository

Examples

## Not run: 

# In an Rmarkdown document:

# For a file in another repository:
# ```{r, echo=FALSE, results='asis'}
borrow_chapter(
  doc_path = "docs/02-chapter_of_course.md",
  repo_name = "jhudsl/OTTR_Template"
)
# ```

# For a local file:
# ```{r, echo=FALSE, results='asis'}
borrow_chapter(doc_path = "02-chapter_of_course.Rmd")
# ```

## End(Not run)

---

Check if a repository exists on GitHub

Description

Given a repository name, check with git ls-remote whether the repository exists and return a TRUE/FALSE

Usage

check_git_repo(
  repo_name,
  git_pat = NULL,
  silent = TRUE,
  return_repo = FALSE,
  verbose = TRUE
)

Arguments

repo_name	the name of the repository, e.g. jhudsl/OTTR_Template
git_pat	A personal access token from GitHub. Only necessary if the repository being checked is a private repository.
silent	TRUE/FALSE of whether the warning from the git ls-remote command should be echoed back if it does fail.
return_repo	TRUE/FALSE of whether or not the output from git ls-remote should be saved to a file (if the repo exists)
verbose	TRUE/FALSE do you want more progress messages?

Value

A TRUE/FALSE whether or not the repository exists. Optionally the output from git ls-remote if return_repo = TRUE.

Examples

check_git_repo("jhudsl/OTTR_Template")

---

Extract entries from a list based on the name

Description

Given a list, extract items based on their name

Usage

extract_entries(api_list, entry_name, fixed = TRUE)

Arguments

api_list	a list (probably from the GitHub api)
entry_name	the name of the entry to be extracted from the api list e.g. "html_url"
fixed	TRUE/FALSE whether or not the exact string should be used. FALSE would mean regex will be interpretted.

Value

a subset of api_list that only contains items with the entry_name string in the name.

Examples

repo_info <- get_repo_info("jhudsl/Documentation_and_Usability")

extract_entries(repo_info, "release", fixed = TRUE)

---

Get artifact file URL

Description

If you have a GitHub actions that uploads an artifact file, this function can retrieve the URL for you to use to download that file.

Usage

get_artifact_url(artifact_name, repo_name = NULL, git_pat = NULL)

Arguments

artifact_name	The job name of the artifact to be retrieved, for example "spell-check-results" document of the chapter in the repository you are retrieving it from that you would like to include in the current document. e.g "docs/intro.md" or "intro.md"
repo_name	A character vector indicating the repo name of where you are borrowing from. e.g. "jhudsl/OTTR_Template/". For a Wiki of a repo, use "wiki/jhudsl/OTTR_Template/" If nothing is provided, will look for local file.
git_pat	A personal access token from GitHub. Only necessary if the repository being checked is a private repository.

Value

A download url for the most recent run that matches the artifact name.

Examples

## Not run: 

# If in GitHub actions you have something like this:

#     - name: Archive spelling errors
#       uses: actions/upload-artifact\@v2
#       with:
#         name: spell-check-results
#         path: spell_check_results.tsv

# This you can run this:

cow::get_artifact_url(
  artifact_name = "spell-check-results",
  repo_name = "jhudsl/OTTR_Template",
  git_pat = "gh_12345"
)

## End(Not run)

---

Retrieve bookdown chapters for a repository

Description

Given an repository on GitHub, retrieve all the bookdown chapter information for the Github page if it exists. Currently only public repositories are supported.

Usage

get_chapters(
  repo_name,
  git_pat = NULL,
  retrieve_learning_obj = FALSE,
  retrieve_keywords = TRUE,
  verbose = TRUE,
  udmodel = NULL
)

Arguments

repo_name	The full name of the repo to get bookdown chapters from. e.g. "jhudsl/OTTR_Template"
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 get_git_auth
retrieve_learning_obj	TRUE/FALSE attempt to retrieve learning objectives?
retrieve_keywords	TRUE/FALSE attempt to retrieve keywords from the chapter?
verbose	TRUE/FALSE do you want more progress messages?
udmodel	A udmodel passed in for keyword determination. Will be obtained using udpipe::udpipe_download_model(language = "english") if its not given.

Value

a data frame with the repository with the following columns: data_level, data_path, chapt_name, url, repository name

Examples

## Not run: 

usethis::create_github_token()

get_chapters("jhudsl/Documentation_and_Usability")

## End(Not run)

---

Handle GitHub PAT authorization

Description

Handle things whether or not a GitHub PAT is supplied.

Usage

get_git_auth(
  git_pat = NULL,
  git_username = "PersonalAccessToken",
  quiet = FALSE
)

Arguments

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().
git_username	Optional, can include username for credentials.
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.

---

Retrieve keywords for a chapter

Description

Given an URL to a bookdown chapter, extract the keywords

Usage

get_keywords(url, min_occurrence = 4, udmodel = NULL)

Arguments

url	a url to a bookdown chapter e.g. "https://jhudatascience.org/Documentation_and_Usability/what-does-good-documentation-look-like.html"
min_occurrence	A numeric number specifying the minimum number of times a keyword should appear for it to stay in the list. Default is 4.
udmodel	A udmodel passed in for keyword determination. Will be obtained using udpipe::udpipe_download_model(language = "english") if its not given.

Value

a data frame of keywords

Examples

# Declare chapter URL
url <- "https://jhudatascience.org/Documentation_and_Usability/other-helpful-features.html"

keywords_df <- get_keywords(url)

---

Retrieve learning objectives for a chapter

Description

Given an repository on GitHub, retrieve all the bookdown chapter information for the Github page if it exists. Currently only public repositories are supported.

Usage

get_learning_obj(url, prompt = "This chapter will demonstrate how to\\:")

Arguments

url	a url to a bookdown chapter e.g. "https://jhudatascience.org/Documentation_and_Usability/what-does-good-documentation-look-like.html"
prompt	A string character that is a prompt lead in to the Learning objectives and should be deleted.

Value

find learning objectives for a particular chapter

Examples

## Not run: 

# Declare chapter URL
url <- "https://jhudatascience.org/Documentation_and_Usability/other-helpful-features.html"

get_learning_obj(url)

## End(Not run)

---

Retrieve pages url for a repo

Description

Given an repository on GitHub, retrieve the pages URL for it.

Usage

get_pages_url(repo_name, git_pat = NULL, verbose = FALSE, keep_json = FALSE)

Arguments

repo_name	The full name of the repo to get bookdown chapters from. e.g. "jhudsl/OTTR_Template"
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 get_git_auth
verbose	TRUE/FALSE do you want more progress messages?
keep_json	verbose TRUE/FALSE keep the json file locally?

Value

a data frame with the repository with the following columns: data_level, data_path, chapt_name, url, repository name

Examples

## Not run: 

usethis::create_github_token()

get_chapters("jhudsl/Documentation_and_Usability")

## End(Not run)

---

Retrieve information about a github repo

Description

Given an repository on GitHub, retrieve the information about it from the GitHub API and read it into R.

Usage

get_release_info(repo_name, git_pat = NULL, verbose = TRUE)

Arguments

repo_name	The full name of the repo to get bookdown chapters from. e.g. "jhudsl/OTTR_Template"
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 get_git_auth
verbose	TRUE/FALSE do you want more progress messages?

Value

a data frame with the repository's release information: tag_name and tag_date. NAs are returned in these columns if there are no releases.

Examples

## Not run: 

release_info <- get_release_info("jhudsl/OTTR_Template")

## End(Not run)

---

Retrieve information about a github repo

Description

Given an repository on GitHub, retrieve the information about it from the GitHub API and read it into R.

Usage

get_repo_info(repo_name, git_pat = NULL, verbose = FALSE)

Arguments

repo_name	The full name of the repo to get bookdown chapters from. e.g. "jhudsl/OTTR_Template"
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 get_git_auth
verbose	TRUE/FALSE do you want more progress messages?

Value

a data frame with the repository with the following columns: data_level, data_path, chapt_name, url, repository name

Examples

repo_info <- get_repo_info("jhudsl/Documentation_and_Usability")

---

Retrieve all bookdown chapters for an org

Description

Given an organization on GitHub, retrieve all the bookdown chapter information for all the Github pages that exist for all the repositories. Currently only public repositories are supported.

Usage

retrieve_org_chapters(
  org_name = NULL,
  output_file = "org_chapter_info.tsv",
  git_pat = NULL,
  retrieve_learning_obj = FALSE,
  retrieve_keywords = TRUE,
  verbose = TRUE
)

Arguments

org_name	the name of the organization that e.g. "jhudsl"
output_file	a file path for where the chapter information should be saved e.g. "jhudsl_chapter.tsv"
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().
retrieve_learning_obj	TRUE/FALSE attempt to retrieve learning objectives?
retrieve_keywords	TRUE/FALSE attempt to retrieve keywords from the chapter?
verbose	TRUE/FALSE do you want more progress messages?

Value

A TRUE/FALSE whether or not the repository exists. Optionally the output from git ls-remote if return_repo = TRUE.

Examples

## Not run: 
retrieve_org_chapters(
  org_name = "jhudsl",
  output_file = "jhudsl_chapter_info.tsv"
)

## End(Not run)

---

Retrieve all bookdown chapters for an org

Description

Given an organization on GitHub, retrieve all the bookdown chapter information for all the Github pages that exist for all the repositories. Currently only public repositories are supported.

Usage

retrieve_org_repos(
  org_name = NULL,
  output_file = "org_repos.tsv",
  git_pat = NULL,
  verbose = TRUE
)

Arguments

org_name	the name of the organization that e.g. "jhudsl"
output_file	a file path for where the chapter information should be saved e.g. "jhudsl_repos.tsv"
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().
verbose	TRUE/FALSE do you want more progress messages?

Value

A TRUE/FALSE whether or not the repository exists. Optionally the output from git ls-remote if return_repo = TRUE.

Examples

retrieve_org_repos(
  org_name = "jhudsl",
  output_file = "jhudsl_repos.tsv"
)

---