Merge pull request #13 from jhudsl/cansavvy/borrow-chapters

Borrow chapters function

.Rbuildignore

@@ -5,12 +5,11 @@
 ^_pkgdown\.yml$
 ^docs$
 ^pkgdown$
-^english-ewt-ud-2.5-191206.udpipe$
 ^jhudsl_chapter_info.tsv$
 ^jhudsl-repos.json$
 ^docker$
 ^.local$
 ^.rstudio$
-^english-ewt-ud-2.5-191206.udpipe$
+^.*udpipe$
 ^\.secrets$
 ^/home/rstudio/cow/\.secrets$

DESCRIPTION

@@ -1,13 +1,13 @@
 Package: cow
-Title: Helps Manage Git Course Repos
+Title: Course Organizer and Wrangler
 Version: 0.0.0.9000
 Authors@R:
     person(given = "Candace",
            family = "Savonen",
            role = c("aut", "cre"),
            email = "[email protected]")
-Description: Accesses GitHub API from R and performs some course
-  management functions, including retrieving chapter names, learning objectives,
+Description: Performs some course management functions through interactions with
+  GitHub API, including retrieving chapter names, learning objectives,
   and keywords for courses hosted on GitHub repositories.
 License: GPL-3
 Imports:
@@ -24,6 +24,8 @@ Imports:
     textrank,
     udpipe,
     xml2,
+    knitr,
+    igraph,
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)

NAMESPACE

@@ -1,5 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+export(borrow_chapter)
 export(check_git_repo)
 export(extract_entries)
 export(get_chapters)
@@ -16,8 +17,10 @@ importFrom(gitcreds,gitcreds_get)
 importFrom(httr,GET)
 importFrom(httr,accept_json)
 importFrom(httr,authenticate)
+importFrom(knitr,knit_child)
 importFrom(magrittr,"%>%")
 importFrom(textrank,textrank_keywords)
 importFrom(udpipe,udpipe_annotate)
 importFrom(udpipe,udpipe_download_model)
 importFrom(udpipe,udpipe_load_model)
+importFrom(utils,download.file)

R/auth_arg.R

@@ -6,42 +6,35 @@
 #' 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().
 #' @param git_username Optional, can include username for credentials.
-#'
+#' @param quiet Use TRUE if you don't want the warning about no GitHub credentials.
+#' 
 #' @return Authorization argument to supply to curl OR a blank string if no
 #' authorization is found or supplied.
 #'
 #' @export
 #'
-get_git_auth <- function(git_pat = NULL, git_username = "PersonalAccessToken") {
-
-  auth_arg <- NULL
+get_git_auth <- function(git_pat = NULL, git_username = "PersonalAccessToken", quiet = FALSE) {
 
-  # If either username or git pat is not provided, try to get credentials with gitcreds
-  if (is.null(git_pat) || is.null(git_username)) {
+  auth_arg <- NULL
+
+  # If git pat is not provided, try to get credentials with gitcreds
+  if (is.null(git_pat)) {
 
     # Try getting credentials
-    creds <- try(gitcreds::gitcreds_get(), silent = TRUE)
+    auth_arg <- try(gitcreds::gitcreds_get(), silent = TRUE)
 
-    if (grepl("Could not find any credentials", creds[1])) {
-      message("Could not find git credentials, please set by running usethis::create_github_token(),
-              or directly providing a personal access token here.")
+    if (grepl("Could not find any credentials", auth_arg[1])) {
 
+      # Only if we're running this interactively
       if (interactive()) {
         # Set credentials if null
         auth_arg <- gitcreds::gitcreds_set()
+      } else {
+        message("Could not find git credentials, please set by running usethis::create_github_token(),
+              or directly providing a personal access token using the git_pat argument")
       }
     }
-
-    git_username <- auth_arg$username
-    git_pat <- auth_arg$password
-
-    if (is.null(git_pat)) {
-      warning("No github credentials found or provided.
-              Only public repositories will be retrieved. Set GitHub token using
-              usethis::create_github_token() if you would like private repos to be included.")
-    }
-  }
-  if (!is.null(git_pat)) {
+  } else { # If git_pat is given, use it.
     # Set to Renviron file temporarily
     Sys.setenv(GITHUB_PAT = git_pat)
 
@@ -56,5 +49,15 @@ get_git_auth <- function(git_pat = NULL, git_username = "PersonalAccessToken") {
     auth_arg$host <- "github.com"
     auth_arg$username <- git_username
   }
+
+  # Check if we have authentication
+  git_pat <- try(auth_arg$password, silent = TRUE)
+
+  if (grepl("Error", git_pat[1])) {
+    if (!quiet) {
+      message("No github credentials found or provided; only public repositories will be successful.")
+    }
+  }
+
   return(auth_arg)
 }

R/borrow_chapter.R

@@ -0,0 +1,82 @@
+#' Borrow/link a chapter from another bookdown course
+#'
+#' @param 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"
+#' @param repo_name A character vector indicating the repo name of where you are
+#'  borrowing from. e.g. "jhudsl/DaSL_Course_Template_Bookdown/".
+#' For a Wiki of a repo, use "wiki/jhudsl/DaSL_Course_Template_Bookdown/"
+#' If nothing is provided, will look for local file.
+#' @param branch Default is to pull from main branch, but need to declare if other branch is needed.
+#' @param git_pat A personal access token from GitHub. Only necessary if the
+#' repository being checked is a private repository.
+#' @param base_url it's assumed this is coming from github so it is by default 'https://raw.githubusercontent.com/'
+#' @param dest_dir A file path where the file should be stored upon arrival to
+#' the current repository.
+#'
+#' @return An Rmarkdown or markdown is knitted into the document from another repository
+#'
+#' @importFrom knitr knit_child
+#' @importFrom utils download.file
+#' @export
+#'
+#' @examples \dontrun{
+#'
+#' # 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/DaSL_Course_Template_Bookdown"
+#' )
+#' # ```
+#'
+#' # For a local file:
+#' # ```{r, echo=FALSE, results='asis'}
+#' borrow_chapter(doc_path = "02-chapter_of_course.Rmd")
+#' # ```
+#' }
+borrow_chapter <- function(doc_path,
+                           repo_name = NULL,
+                           branch = "main",
+                           git_pat = NULL,
+                           base_url = "https://raw.githubusercontent.com",
+                           dest_dir = file.path("resources", "other_chapters")) {
+
+
+  # Declare file names
+  doc_path <- file.path(doc_path)
+  doc_name <- basename(doc_path)
+
+  if (is.null(repo_name)) {
+    exists <- check_git_repo(
+      repo_name = repo_name,
+      git_pat = git_pat,
+      verbose = FALSE,
+      silent = TRUE
+    )
+
+    # Create folder if it doesn't exist
+    if (!dir.exists(dest_dir)) {
+      dir.create(dest_dir, recursive = TRUE)
+    }
+
+    dest_file <- file.path(dest_dir, doc_name)
+
+    full_url <- file.path(base_url, repo_name, branch, doc_path)
+
+    # Progress message
+    message(full_url)
+
+    # Download it
+    download.file(full_url, destfile = dest_file)
+  } else {
+    # If the file is local we don't need to download anything
+    dest_file <- doc_path
+  }
+
+  # Knit it in
+  result <- knitr::knit_child(dest_file, quiet = TRUE)
+  cat(result, sep = "\n")
+}

R/check_git_repo.R

@@ -24,38 +24,31 @@ check_git_repo <- function(repo_name,
                            silent = TRUE,
                            return_repo = FALSE,
                            verbose = TRUE) {
-
   if (verbose) {
     message(paste("Checking for remote git repository:", repo_name))
   }
   # If silent = TRUE don't print out the warning message from the 'try'
   report <- ifelse(silent, suppressWarnings, message)
 
-  if (is.null(git_pat)) {
-    git_pat <- gitcreds::gitcreds_get()$password
-    if (is.null(git_pat)) {
-      warning("No github credentials found or provided.
-              Only public repositories will be retrieved. Set GitHub token using
-              usethis::create_github_token()
-              if you would like private repos to be included.")
-    }
-  }
+  # Try to get credentials
+  auth_arg <- get_git_auth(git_pat = git_pat, quiet = !verbose)
 
-  if (!is.null(git_pat)) {
+  git_pat <- try(auth_arg$password, silent = TRUE)
+
+  # Run git ls-remote
+  if (!grepl("Error", git_pat[1])) {
     # If git_pat is supplied, use it
     test_repo <- report(
       try(system(paste0("git ls-remote https://", git_pat, "@github.com/", repo_name),
         intern = TRUE, ignore.stderr = TRUE
       ))
     )
   } else {
-
     # Try to git ls-remote the repo_name given
-    test_repo <- report(
-      try(system(paste0("git ls-remote https://github.com/", repo_name),
-        intern = TRUE, ignore.stderr = TRUE
-      ))
-    )
+    test_repo <- report
+    try(system(paste0("git ls-remote https://github.com/", repo_name),
+      intern = TRUE, ignore.stderr = TRUE
+    ))
   }
   # If 128 is returned as a status attribute it means it failed
   exists <- ifelse(is.null(attr(test_repo, "status")), TRUE, FALSE)

R/get_chapters.R

@@ -28,9 +28,13 @@ utils::globalVariables(c(
 #'
 #' @export
 #'
-#' @examples
+#' @examples \dontrun{
 #'
+#' usethis::create_github_token()
+#' 
 #' get_chapters("jhudsl/Documentation_and_Usability")
+#' 
+#' }
 get_chapters <- function(repo_name,
                          git_pat = NULL,
                          retrieve_learning_obj = FALSE,

R/get_learning_obj.R

@@ -17,12 +17,13 @@
 #'
 #' @export
 #'
-#' @examples
+#' @examples \dontrun{
 #'
 #' # Declare chapter URL
 #' url <- "https://jhudatascience.org/Documentation_and_Usability/other-helpful-features.html"
 #'
 #' get_learning_obj(url)
+#' }
 get_learning_obj <- function(url, prompt = "This chapter will demonstrate how to\\:") {
 
   # Try chapter url

R/get_pages_url.R

@@ -19,24 +19,34 @@
 #'
 #' @export
 #'
-#' @examples
+#' @examples \dontrun{
 #'
-#' pages_url <- get_pages_url("jhudsl/DaSL_Course_Template_Bookdown")
+#' usethis::create_github_token()
+#' 
+#' get_chapters("jhudsl/Documentation_and_Usability")
+#' 
+#' }
 get_pages_url <- function(repo_name,
                           git_pat = NULL,
                           verbose = FALSE,
                           keep_json = FALSE) {
   page_url <- NA
 
-  # Build auth argument
-  auth_arg <- get_git_auth(git_pat = git_pat)
+  # Try to get credentials other way
+  auth_arg <- get_git_auth(git_pat = git_pat, quiet = !verbose)
+
+  git_pat <- try(auth_arg$password, silent = TRUE)
+
+  if (grepl("Error", git_pat[1])) {
+    warning("Cannot retrieve page info without GitHub credentials. Passing an NA.")
+  }
 
   # We can only retrieve pages if we have the credentials
-  if (!is.null(auth_arg$password)) {
+  if (!grepl("Error", git_pat[1])) {
     exists <- check_git_repo(
       repo_name = repo_name,
       git_pat = git_pat,
-      verbose = verbose
+      verbose = FALSE
     )
 
     if (exists) {
@@ -67,8 +77,6 @@ get_pages_url <- function(repo_name,
         page_url <- page_info$html_url
       }
     }
-  } else {
-    warning("Cannot retrieve page info without GitHub credentials. Passing an NA.")
   }
   return(page_url)
 }