move to using markdown docs

Author: sckott

R/commits.R

@@ -5,7 +5,7 @@
 #' @param page (integer) Page number to return.
 #' @param per_page (integer) Number of items to return per page. 
 #' Default 30. Max 100.
-#' @param ... Further named args to \code{\link[httr]{GET}}
+#' @param ... Further named args to [httr::GET()]
 #' @examples \dontrun{
 #' gists()[[1]] %>% commits()
 #' gist(id = '1f399774e9ecc9153a6f') %>% commits(per_page = 5)

R/forks.R

@@ -5,7 +5,7 @@
 #' @param page (integer) Page number to return.
 #' @param per_page (integer) Number of items to return per page. Default 30. 
 #' Max 100.
-#' @param ... Further named args to \code{\link[httr]{GET}}
+#' @param ... Further named args to [httr::GET()]
 #' @return A list of gist class objects
 #' @examples \dontrun{
 #' gist(id='1642874') %>% forks(per_page=2)

R/gist.R

@@ -9,7 +9,7 @@
 #' @details If a file is larger than ~1 MB, the content of the file given back 
 #' is truncated, so you won't get the entire contents. In the return S3 object
 #' that's printed, we tell you at the bottom whether each file is truncated or 
-#' not. If a file is, simply get the \code{raw_url} URL for the file (see 
+#' not. If a file is, simply get the `raw_url` URL for the file (see 
 #' example below), then retrieve from that. If the file is very big, you may 
 #' need to clone the file using git, etc. 
 #' @examples \dontrun{

R/gist_auth.R

@@ -4,18 +4,17 @@
 #' account.
 #'
 #' There are two ways to authorise gistr to work with your GitHub account:
-#' \itemize{
-#'  \item Generate a personal access token at
-#'    \url{https://help.github.com/articles/creating-an-access-token-for-command-line-use} 
-#'    and record in the \code{GITHUB_PAT} envar.
-#'  \item Interactively login into your GitHub account and authorise with OAuth.
-#' }
+#' 
+#' - Generate a personal access token at
+#'    <https://help.github.com/articles/creating-an-access-token-for-command-line-use>
+#'    and record in the `GITHUB_PAT` envar.
+#' - Interactively login into your GitHub account and authorise with OAuth.
 #'
-#' Using \code{GITHUB_PAT} is recommended.
+#' Using `GITHUB_PAT` is recommended.
 #'
 #' @export
-#' @param app An \code{\link[httr]{oauth_app}} for GitHub. The default uses an 
-#' application \code{gistr_oauth} created by Scott Chamberlain.
+#' @param app An [httr::oauth_app()] for GitHub. The default uses an 
+#' application `gistr_oauth` created by Scott Chamberlain.
 #' @param reauth (logical) Force re-authorization?
 #' @examples \dontrun{
 #' gist_auth()

R/gist_create.R

@@ -2,10 +2,9 @@
 #'
 #' @export
 #' @template args
-#' @param rmarkdown (logical) If \code{TRUE}, use 
-#' \code{\link[rmarkdown]{render}} instead of \code{\link[knitr]{knit}} to 
-#' render the document.
-#' @seealso \code{\link{gist_create_obj}}, \code{\link{gist_create_git}}
+#' @param rmarkdown (logical) If `TRUE`, use [rmarkdown::render()] instead of
+#' [knitr::knit()] to render the document.
+#' @seealso [gist_create_obj()], [gist_create_git()]
 #' @examples \dontrun{
 #' file <- tempfile()
 #' cat("hello world", file = file)

R/gist_create_git.R

@@ -4,17 +4,17 @@
 #' 
 #' @template args
 #' @param artifacts (logical/character) Include artifacts or not. 
-#' If \code{TRUE}, includes all artifacts. Or you can pass in a file extension 
-#' to only upload artifacts of certain file exensions. Default: \code{FALSE}
+#' If `TRUE`, includes all artifacts. Or you can pass in a file extension 
+#' to only upload artifacts of certain file exensions. Default: `FALSE`
 #' @param git_method (character) One of ssh (default) or https. If a remote 
 #' already exists, we use that remote, and this parameter is ignored. 
 #' @param sleep (integer) Seconds to sleep after creating gist, but before 
 #' collecting metadata on the gist. If uploading a lot of stuff, you may want to
 #' set this to a higher value, otherwise, you may not get accurate metadata for
-#' your gist. You can of course always refresh afterwards by calling \code{gist}
+#' your gist. You can of course always refresh afterwards by calling `gist`
 #' with your gist id.
 #' 
-#' @details Note that when \code{browse=TRUE} there is a slight delay in when 
+#' @details Note that when `browse=TRUE` there is a slight delay in when 
 #' we open up the gist in your default browser and when the data will display 
 #' in the gist. We could have this function sleep a while and guess when it 
 #' will be ready, but instead we open your gist right after we're done sending
@@ -23,32 +23,30 @@
 #' 
 #' Likewise, the object that is returned from this function call may not have 
 #' the updated and correct file information. You can retrieve that easily by 
-#' calling \code{\link{gist}} with the gist id. 
+#' calling [gist()] with the gist id. 
 #' 
 #' This function uses git instead of the HTTP API, and thus requires
-#' the R package \code{git2r}. If you don't have \code{git2r} installed, and 
-#' try to use this function, it will stop and tell you to install \code{git2r}.
+#' the R package `git2r`. If you don't have `git2r` installed, and 
+#' try to use this function, it will stop and tell you to install `git2r`.
 #' 
-#' This function using git is better suited than \code{\link{gist_create}}
+#' This function using git is better suited than [gist_create()]
 #' for use cases involving:
 #' 
-#' \itemize{
-#'  \item Big files - The GitHub API allows only files of up to 1 MB in size. 
+#' - Big files - The GitHub API allows only files of up to 1 MB in size. 
 #'  Using git we can get around that limit.
-#'  \item Binary files - Often artifacts created are binary files like 
-#'  \code{.png}. The GitHub API doesn't allow transport of binary files, but 
+#' - Binary files - Often artifacts created are binary files like 
+#'  `.png`. The GitHub API doesn't allow transport of binary files, but 
 #'  we can do that with git. 
-#' }
 #' 
-#' Another difference between this function and \code{\link{gist_create}} is 
+#' Another difference between this function and [gist_create()] is 
 #' that this function can collect all artifacts coming out of a knit process.
 #' 
 #' If a gist is somehow deleted, or the remote changes, when you try to push 
 #' to the same gist again, everything should be fine. We now use 
-#' \code{tryCatch} on the  push attempt, and if it fails, we'll add a new 
+#' `tryCatch` on the  push attempt, and if it fails, we'll add a new 
 #' remote (which means a new gist), and push again.
 #' 
-#' @seealso \code{\link{gist_create}}, \code{\link{gist_create_obj}}
+#' @seealso [gist_create()], [gist_create_obj()]
 #' 
 #' @examples \dontrun{
 #' # prepare a directory and a file

R/gist_create_obj.R

@@ -4,16 +4,16 @@
 #'
 #' @param x An R object, any of data.frame, matrix, list, character, numeric
 #' @param description (character) Brief description of gist (optional)
-#' @param public (logical) Whether gist is public (default: TRUE)
-#' @param browse (logical) To open newly create gist in default browser 
-#' (default: TRUE)
+#' @param public (logical) Whether gist is public (default: `TRUE`)
+#' @param browse (logical) To open newly create gist in default browser
+#' (default: `TRUE`)
 #' @param pretty (logical) For data.frame and matrix objects, create
-#' a markdown table. If FALSE, pushes up json. (default: TRUE)
-#' @param filename Name of the file to create. Default: \code{file.txt}
-#' @param ... Further args passed on to \code{link[httr]{POST}}
-#' @details This function is specifically for going from R objects to a gist, 
-#' whereas \code{\link{gist_create}} is for going from files or executing code
-#' @seealso \code{\link{gist_create}}, \code{\link{gist_create_git}}
+#' a markdown table. If FALSE, pushes up json. (default: `TRUE`)
+#' @param filename Name of the file to create. Default: `file.txt`
+#' @param ... Further args passed on to [httr::POST()]
+#' @details This function is specifically for going from R objects to a gist,
+#' whereas [gist_create()] is for going from files or executing code
+#' @seealso [gist_create()], [gist_create_git()]
 #' @examples \dontrun{
 #' ## data.frame
 #' ### by default makes pretty table in markdown format
@@ -39,49 +39,49 @@
 #' hey there!", filename = "my_markdown.md")
 #' }
 gist_create_obj <- function(x = NULL, description = "", public = TRUE,
-                            browse = TRUE, pretty = TRUE, 
+                            browse = TRUE, pretty = TRUE,
                             filename = "file.txt", ...) {
   UseMethod("gist_create_obj")
 }
 
 #' @export
 gist_create_obj.data.frame <- function(x = NULL, description = "", public = TRUE,
-                                       browse = TRUE, pretty = TRUE, 
+                                       browse = TRUE, pretty = TRUE,
                                        filename = "file.txt", ...) {
   gc_robjs(x, description, public, browse, pretty, filename, ...)
 }
 
 #' @export
 gist_create_obj.character <- function(x = NULL, description = "", public = TRUE,
-                                      browse = TRUE, pretty = TRUE, 
+                                      browse = TRUE, pretty = TRUE,
                                       filename = "file.txt", ...) {
   gc_robjs(x, description, public, browse, pretty, filename, ...)
 }
 
 #' @export
 gist_create_obj.list <- function(x = NULL, description = "", public = TRUE,
-                                 browse = TRUE, pretty = TRUE, 
+                                 browse = TRUE, pretty = TRUE,
                                  filename = "file.txt", ...) {
   gc_robjs(x, description, public, browse, pretty, filename, ...)
 }
 
 #' @export
 gist_create_obj.matrix <- function(x = NULL, description = "", public = TRUE,
-                                   browse = TRUE, pretty = TRUE, 
+                                   browse = TRUE, pretty = TRUE,
                                    filename = "file.txt", ...) {
   gc_robjs(x, description, public, browse, pretty, filename, ...)
 }
 
 #' @export
 gist_create_obj.numeric <- function(x = NULL, description = "", public = TRUE,
-                                    browse = TRUE, pretty = TRUE, 
+                                    browse = TRUE, pretty = TRUE,
                                     filename = "file.txt", ...) {
   gc_robjs(x, description, public, browse, pretty, filename, ...)
 }
 
 #' @export
 gist_create_obj.json <- function(x = NULL, description = "", public = TRUE,
-                                 browse = TRUE, pretty = TRUE, 
+                                 browse = TRUE, pretty = TRUE,
                                  filename = "file.txt", ...) {
   gc_robjs(unclass(x), description, public, browse, pretty, filename, ...)
 }

R/gist_map.R

@@ -3,9 +3,9 @@
 #' Takes a gist object and a input geojson file name and renders fullscreen map
 #' 
 #' @export
-#' @param x An object of class \code{gist} generated by 
-#' \code{\link{gist_create}} or \code{\link{gist_create_obj}}
-#' @param browse Default: \code{TRUE}. Set to \code{FALSE} if you don't want to 
+#' @param x An object of class `gist` generated by 
+#' [gist_create()] or [gist_create_obj()]
+#' @param browse Default: `TRUE`. Set to `FALSE` if you don't want to 
 #' automatically browse to the URL.
 #' @examples \dontrun{
 #' file <- system.file("examples", "ecoengine_eg.geojson", package = "gistr")

R/gist_save.R

@@ -2,25 +2,25 @@
 #'
 #' @export
 #' @param gist A gist object or something coerceable to a gist
-#' @param path Root path to write to, a directory, not a file b/c a gist can 
-#' contain  many files. A folder is created with name of the gist id within 
+#' @param path Root path to write to, a directory, not a file b/c a gist can
+#' contain  many files. A folder is created with name of the gist id within
 #' this root directory.  File names will be the same as given in the gist.
-#' @param x An object of class \code{gist_files} (the output from 
-#' \code{gist_save})
-#' @return An object of class \code{gist_files}, S3 object containing file 
+#' @param x An object of class `gist_files` (the output from
+#' [gist_save()]
+#' @return An object of class `gist_files`, S3 object containing file
 #' paths
-#' @details 
-#' \code{gist_save}: files are written into a new folder, named by the gist id, 
-#' e.g., \code{a65ac7e56b7b3f746913}
-#' 
-#' \code{gist_open}: opens files in your editor/R GUI. Internally, uses 
-#' \code{\link{file.edit}} to open files, using \code{getOption("editor")} to 
-#' open the files. If you're in R.app or RStudio, or other IDE's, files will 
+#' @details
+#' `gist_save`: files are written into a new folder, named by the gist id,
+#' e.g., `a65ac7e56b7b3f746913`
+#'
+#' `gist_open`: opens files in your editor/R GUI. Internally, uses
+#' [file.edit()] to open files, using `getOption("editor")` to
+#' open the files. If you're in R.app or RStudio, or other IDE's, files will
 #' open in the IDE (I think).
 #' @examples \dontrun{
 #' gist("a65ac7e56b7b3f746913") %>% gist_save()
 #' gist("a65ac7e56b7b3f746913") %>% gist_save() %>% gist_open()
-#' gist("https://gist.github.com/expersso/4ac33b9c00751fddc7f8") %>% 
+#' gist("https://gist.github.com/expersso/4ac33b9c00751fddc7f8") %>%
 #'   gist_save()
 #' }
 
@@ -44,7 +44,7 @@ gist_save <- function(gist, path = ".") {
 #' @export
 print.gist_files <- function(x, ...) {
   cat("<gist> ", attr(x, "id"), "\n", sep = "")
-  cat(g_wrap(sprintf("Files:\n %s ...", paste0(x, collapse = "\n")), 
+  cat(g_wrap(sprintf("Files:\n %s ...", paste0(x, collapse = "\n")),
              indent = 3), "\n\n")
 }
 
@@ -67,6 +67,6 @@ isDir <- function(path) {
   file.info(path)$isdir
 }
 
-is.string <- function(x) { 
+is.string <- function(x) {
   is.character(x) && length(x) == 1
 }

R/gistr-package.R

@@ -1,26 +1,24 @@
 #' R client for GitHub gists.
 #'
-#' gistr allows you to peform actions on gists, including listing, forking, 
+#' gistr allows you to peform actions on gists, including listing, forking,
 #' starring, creating, deleting, updating, etc.
 #'
 #' There are two ways to authorise gistr to work with your GitHub account:
 #'
-#' \itemize{
-#'  \item Generate a personal access token (PAT) at
-#'  \url{https://help.github.com/articles/creating-an-access-token-for-command-line-use}
-#'  and record it in the \code{GITHUB_PAT} envar.
-#'  \item Interactively login into your GitHub account and authorise with OAuth.
-#' }
+#' - Generate a personal access token (PAT) at
+#'  <https://help.github.com/articles/creating-an-access-token-for-command-line-use>
+#'  and record it in the `GITHUB_PAT` envar.
+#' - Interactively login into your GitHub account and authorise with OAuth.
 #'
-#' Using the \code{GITHUB_PAT} is recommended.
+#' Using the `GITHUB_PAT` is recommended.
 #'
 #' @importFrom magrittr %>%
 #' @importFrom knitr knit
 #' @importFrom rmarkdown render
-#' @importFrom httr GET POST PATCH PUT DELETE content stop_for_status 
+#' @importFrom httr GET POST PATCH PUT DELETE content stop_for_status
 #' add_headers warn_for_status
 #' @importFrom assertthat assert_that has_extension
-#' @importFrom dplyr bind_rows as_data_frame 
+#' @importFrom dplyr bind_rows as_data_frame
 #' @importFrom jsonlite flatten
 #' @name gistr-package
 #' @aliases gistr
@@ -34,30 +32,28 @@ NULL
 
 #' @title Create gists
 #'
-#' @description Creating gists in \code{gistr} can be done with any of 
+#' @description Creating gists in `gistr` can be done with any of
 #' three functions:
-#' 
-#' \itemize{
-#'  \item \code{\link{gist_create}} - Create gists from files or code blocks, 
-#'  using  the GitHub HTTP API. Because this function uses the GitHub HTTP API, 
-#'  it does not work for binary files. However, you can get around this for 
-#'  images by using knitr's hook to upload images to eg., imgur. In addition, 
+#'
+#' - [gist_create()] - Create gists from files or code blocks,
+#'  using  the GitHub HTTP API. Because this function uses the GitHub HTTP API,
+#'  it does not work for binary files. However, you can get around this for
+#'  images by using knitr's hook to upload images to eg., imgur. In addition,
 #'  it's difficult to include artifacts from the knit-ing process.
-#'  \item \code{\link{gist_create_git}} - Create gists from files or code 
-#'  blocks, using  git. Because this function uses git, you have more 
-#'  flexibility than with the above function: you can include any binary files, 
-#'  and can easily upload all artifacts. \item \code{\link{gist_create_obj}} - 
-#'  Create gists from R objects: data.frame, list, 
+#' - [gist_create_git()] - Create gists from files or code
+#'  blocks, using  git. Because this function uses git, you have more
+#'  flexibility than with the above function: you can include any binary files,
+#'  and can easily upload all artifacts. 
+#' - [gist_create_obj()] - Create gists from R objects: data.frame, list,
 #'  character string, matrix, or numeric. Uses the GitHub HTTP API.
-#' }
-#' 
-#' It may seem a bit odd to have three separate functions for creating gists. 
-#' \code{\link{gist_create}} was created first, and was out for a bit, so when 
-#' we had the idea to create gists via git (\code{\link{gist_create_git}}) and 
-#' from R objects (\code{\link{gist_create_obj}}), it made sense to have a 
-#' different API for creating gists via the HTTP API, git, and from R objects. 
-#' We could have thrown everything into \code{\link{gist_create}}, but it would 
-#' have been a massive function, with far too many parameters. 
+#'
+#' It may seem a bit odd to have three separate functions for creating gists.
+#' [gist_create()] was created first, and was out for a bit, so when
+#' we had the idea to create gists via git ([gist_create_git()]) and
+#' from R objects ([gist_create_obj()]), it made sense to have a
+#' different API for creating gists via the HTTP API, git, and from R objects.
+#' We could have thrown everything into [gist_create()], but it would
+#' have been a massive function, with far too many parameters.
 #'
 #' @name create_gists
 NULL