From 3c98c2c9939305d7b4a8837f030f917bb2397052 Mon Sep 17 00:00:00 2001 From: Noam Ross Date: Mon, 27 Nov 2023 22:21:02 -0500 Subject: [PATCH] clean up docs --- R/get_file_version.R | 22 ++++++++++--------- R/tar_meta_version.R | 29 ++++++++++++++----------- R/tar_read_version.R | 46 ++++++++++++++++++++++----------------- man/get_file_version.Rd | 22 ++++++++++--------- man/relic-package.Rd | 2 -- man/tar_meta_version.Rd | 30 +++++++++++++++----------- man/tar_read_version.Rd | 48 ++++++++++++++++++++--------------------- 7 files changed, 108 insertions(+), 91 deletions(-) diff --git a/R/get_file_version.R b/R/get_file_version.R index 58e2949..3079fb9 100644 --- a/R/get_file_version.R +++ b/R/get_file_version.R @@ -1,23 +1,25 @@ #' Get in files from versioned repository #' #' Fetches the contents of a file from a versioned repository - a local git -#' repository, a GitHub repository, or an S3 bucket. Always fetches the file -#' to a local cache and returns the path to it. +#' repository, a GitHub repository, or an S3 bucket. Always fetches the file to +#' a local cache and returns the path to it. #' #' @param path Path of a file relative to the git directory or bucket #' @param ref A git commit SHA, tag, branch or other [revision #' string](https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions): -#' such as "HEAD~1", "main@{2023-02-26 18:30:00}", or "branch@{yesterday}". -#' Can also be a [git2r::commit()] object. For S3 buckets, a VersionID. -#' Defaults to "HEAD", which also means the latest version in an S3 bucket. +#' such as `"HEAD~1"`, `"main@{2023-02-26 18:30:00}"`, or +#' `"branch@{yesterday}"`. Can also be a [git2r::commit()] object. For S3 +#' buckets, a VersionID. Defaults to "HEAD", which also means the latest +#' version in an S3 bucket. #' @param repo The repository to get the file from. This can be a local git -#' directory, a GitHub repository (URL or "owner/repo" string), or an S3 bucket -#' indicated by "s3://bucket-name". Defaults to the current working directory. +#' directory, a GitHub repository (URL or `"owner/repo"` string), or an S3 +#' bucket indicated by "s3://bucket-name". Defaults to the current working +#' directory. #' @param endpoint,region For S3 buckets, the endpoint and region of the bucket. -#' If NULL, the default endpoint and region in local config or environment variables are used. -#' (Usually `us-east-1` and `s3.amazonaws.com`.) +#' If NULL, the default endpoint and region in local config or environment +#' variables are used. (Usually `us-east-1` and `s3.amazonaws.com`.) #' @export -#' @return A [path][fs::path()] to the file in the local cache. +#' @return A [path][fs::fs_path()] to the file in the local cache. get_file_version <- function(path, ref = "HEAD", repo = ".", endpoint = NULL, region = NULL) { if (!is_scalar_character(path)) { stop("path must be a single string") diff --git a/R/tar_meta_version.R b/R/tar_meta_version.R index 8e03626..e02114a 100644 --- a/R/tar_meta_version.R +++ b/R/tar_meta_version.R @@ -1,24 +1,29 @@ #' Read a target project's metadata from repository history #' -#' This function extracts [targets metadata][targets::tar_meta()] from versioned history. -#' In most cases this is a git repository, but it can also be an S3 cloud bucket -#' for a project using cloud versioning and storing the metadata file in the cloud. -#' (See `repository_meta` in [targets::tar_option_set()]). +#' This function extracts [targets metadata][targets::tar_meta()] from versioned +#' history. In most cases this is a git repository, but it can also be an S3 +#' cloud bucket for a project using cloud versioning and storing the metadata +#' file in the cloud. (See `repository_meta` in [targets::tar_option_set()]). #' #' @param ref A git commit SHA, tag, branch or other [revision #' string](https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions): -#' such as "HEAD~1", "main@{2023-02-26 18:30:00}", or "branch@{yesterday}". -#' Can also be a [git2r::commit()] object. For S3 buckets, a VersionID. -#' Defaults to "HEAD", which also means the latest version in an S3 bucket. -#' @param store Path to the targets store within the project. Defaults to `"_targets`, or the current project's [store name][targets::tar_path_store()] if `repo = "."`. +#' such as `"HEAD~1"`, `"main@{2023-02-26 18:30:00}"`, or +#' `"branch@{yesterday}"`. Can also be a [git2r::commit()] object. For S3 +#' buckets, a VersionID. Defaults to "HEAD", which also means the latest +#' version in an S3 bucket. +#' @param store Path to the targets store within the project. Defaults to +#' `"_targets`, or the current project's [store +#' name][targets::tar_path_store()] if `repo = "."`. #' @param repo The repository to get the file from. This can be a local git -#' directory, a GitHub repository (URL or "owner/repo" string), or an S3 bucket -#' indicated by "s3://bucket-name". Defaults to the current working directory. +#' directory, a GitHub repository (URL or `"owner/repo"` string), or an S3 +#' bucket indicated by "s3://bucket-name". Defaults to the current working +#' directory. #' @param endpoint,region For S3 buckets, the endpoint and region of the bucket. #' @param ... Arguments passed to [targets::tar_meta()] -#' @return A data frame with one row per target/object. See [targets::tar_meta()] for details. +#' @return A data frame with one row per target/object. See +#' [targets::tar_meta()] for details. #' @export -tar_meta_version <- function(ref = "HEAD", store = NULL, repo = ".", endpoint = NULL, region = NULL, ...) { +tar_meta_version <- function(ref = "HEAD", repo = ".", store = NULL, endpoint = NULL, region = NULL, ...) { check_installed("targets") if (is.null(store)) { store <- if (repo == ".") targets::tar_config_get("store") else "_targets" diff --git a/R/tar_read_version.R b/R/tar_read_version.R index 7ccd6c4..c554580 100644 --- a/R/tar_read_version.R +++ b/R/tar_read_version.R @@ -1,31 +1,37 @@ #' Read a target's value from a git repository #' -#' Reads the content of targets from a git repository. Target metadata and -#' local target files are extracted into a temporary directory before being -#' read in by `tar_read()`. For targets of type "file", the files are also -#' extracted and the paths to the extracted files are returned. +#' Reads the content of targets from a git repository. Target metadata and local +#' target files are extracted into a temporary directory before being read in by +#' `tar_read()`. For targets of type "file", the files are also extracted and +#' the paths to the extracted files are returned. #' -#' For cloud targets, the target metadata is read from git history and then -#' this metadata is used to download the target from the cloud. For this to work, +#' For cloud targets, the target metadata is read from git history and then this +#' metadata is used to download the target from the cloud. For this to work, #' cloud storage must be set up with versioning. Note that targets metadata -#' includes the bucket, endpoint, and region of a S3-stored target, but you must still -#' provide an AWS access key and secret as environment variables. If these differ -#' from the credentials used for your current project or environment, can use -#' [withr::with_envvar()] to temporarily set the credentials. +#' includes the bucket, endpoint, and region of a S3-stored target, but you must +#' still provide an AWS access key and secret as environment variables. If these +#' differ from the credentials used for your current project or environment, can +#' use [withr::with_envvar()] to temporarily set the credentials. #' -#' @param name Name of the target. `tar_read_version()` can take a symbol, `tar_read_raw_version()` requires a character. +#' @param name Name of the target. `tar_read_version()` can take a symbol, +#' `tar_read_raw_version()` requires a character. #' @param ref A git commit SHA, tag, branch or other [revision #' string](https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions): -#' such as "HEAD~1", "main@{2023-02-26 18:30:00}", or "branch@{yesterday}". -#' Can also be a [git2r::commit()] object. For S3 buckets, a VersionID. -#' Defaults to "HEAD", which also means the latest version in an S3 bucket. -#' @param store Path to the targets store within the project. Defaults to `"_targets`, or the current project's [store name][targets::tar_path_store()] if `repo = "."`. +#' such as `"HEAD~1"`, `"main@{2023-02-26 18:30:00}"`, or +#' `"branch@{yesterday}"`. Can also be a [git2r::commit()] object. For S3 +#' buckets, a VersionID. Defaults to "HEAD", which also means the latest +#' version in an S3 bucket. +#' @param store Path to the targets store within the project. Defaults to +#' `"_targets`, or the current project's [store +#' name][targets::tar_path_store()] if `repo = "."`. #' @param repo The repository to get the file from. This can be a local git -#' directory, a GitHub repository (URL or "owner/repo" string), or an S3 bucket -#' indicated by "s3://bucket-name". Defaults to the current working directory. +#' directory, a GitHub repository (URL or `"owner/repo"` string), or an S3 +#' bucket indicated by "s3://bucket-name". Defaults to the current working +#' directory. #' @export -#' @return The target's value. If the target is of `format = "file"`, this will be the path to the file in the [relic cache][relic_cache()]. -tar_read_version <- function(name, ref = "HEAD", repo = ".", store = targets::tar_path_store()) { +#' @return The target's value. If the target is of `format = "file"`, this will +#' be the path to the file in the [relic cache][relic_cache()]. +tar_read_version <- function(name, ref = "HEAD", repo = ".", store = NULL) { check_installed("targets") name <- targets::tar_deparse_language(substitute(name)) tar_read_raw_version(name, ref, repo, store) @@ -35,7 +41,7 @@ tar_read_version <- function(name, ref = "HEAD", repo = ".", store = targets::ta #' @export tar_read_raw_version <- function(name, ref = "HEAD", repo = ".", store = NULL) { check_installed("targets") - meta <- tar_meta_version(ref = ref, store = store, repo = repo) + meta <- tar_meta_version(ref = ref, repo = repo, store = store) path_store <- attr(meta, "path_store") index <- meta$name == name if (!any(index) || sum(index) > 1) { diff --git a/man/get_file_version.Rd b/man/get_file_version.Rd index e0e9fdb..9020b37 100644 --- a/man/get_file_version.Rd +++ b/man/get_file_version.Rd @@ -16,23 +16,25 @@ get_file_version( \item{path}{Path of a file relative to the git directory or bucket} \item{ref}{A git commit SHA, tag, branch or other \href{https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions}{revision string}: -such as "HEAD~1", "main@{2023-02-26 18:30:00}", or "branch@{yesterday}". -Can also be a \code{\link[git2r:commit]{git2r::commit()}} object. For S3 buckets, a VersionID. -Defaults to "HEAD", which also means the latest version in an S3 bucket.} +such as \code{"HEAD~1"}, \code{"main@{2023-02-26 18:30:00}"}, or +\code{"branch@{yesterday}"}. Can also be a \code{\link[git2r:commit]{git2r::commit()}} object. For S3 +buckets, a VersionID. Defaults to "HEAD", which also means the latest +version in an S3 bucket.} \item{repo}{The repository to get the file from. This can be a local git -directory, a GitHub repository (URL or "owner/repo" string), or an S3 bucket -indicated by "s3://bucket-name". Defaults to the current working directory.} +directory, a GitHub repository (URL or \code{"owner/repo"} string), or an S3 +bucket indicated by "s3://bucket-name". Defaults to the current working +directory.} \item{endpoint, region}{For S3 buckets, the endpoint and region of the bucket. -If NULL, the default endpoint and region in local config or environment variables are used. -(Usually \code{us-east-1} and \code{s3.amazonaws.com}.)} +If NULL, the default endpoint and region in local config or environment +variables are used. (Usually \code{us-east-1} and \code{s3.amazonaws.com}.)} } \value{ -A \link[fs:path]{path} to the file in the local cache. +A \link[fs:fs_path]{path} to the file in the local cache. } \description{ Fetches the contents of a file from a versioned repository - a local git -repository, a GitHub repository, or an S3 bucket. Always fetches the file -to a local cache and returns the path to it. +repository, a GitHub repository, or an S3 bucket. Always fetches the file to +a local cache and returns the path to it. } diff --git a/man/relic-package.Rd b/man/relic-package.Rd index 3d4621c..7a578b9 100644 --- a/man/relic-package.Rd +++ b/man/relic-package.Rd @@ -6,8 +6,6 @@ \alias{relic-package} \title{Objects from a while back} \description{ -\if{html}{\figure{logo.png}{options: style='float: right' alt='logo' width='120'}} - The 'relic' package provides tools for extracting files and objects from the revision history, including local and remote git repositories and S3 buckets. It is a high-level interface designed to enable comparison of objects in reproducible research workflows, especially pipelines that use the 'targets' package. } \seealso{ diff --git a/man/tar_meta_version.Rd b/man/tar_meta_version.Rd index 00e999e..e7c6010 100644 --- a/man/tar_meta_version.Rd +++ b/man/tar_meta_version.Rd @@ -6,8 +6,8 @@ \usage{ tar_meta_version( ref = "HEAD", - store = NULL, repo = ".", + store = NULL, endpoint = NULL, region = NULL, ... @@ -15,26 +15,30 @@ tar_meta_version( } \arguments{ \item{ref}{A git commit SHA, tag, branch or other \href{https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions}{revision string}: -such as "HEAD~1", "main@{2023-02-26 18:30:00}", or "branch@{yesterday}". -Can also be a \code{\link[git2r:commit]{git2r::commit()}} object. For S3 buckets, a VersionID. -Defaults to "HEAD", which also means the latest version in an S3 bucket.} - -\item{store}{Path to the targets store within the project. Defaults to \verb{"_targets}, or the current project's \link[targets:tar_path_store]{store name} if \code{repo = "."}.} +such as \code{"HEAD~1"}, \code{"main@{2023-02-26 18:30:00}"}, or +\code{"branch@{yesterday}"}. Can also be a \code{\link[git2r:commit]{git2r::commit()}} object. For S3 +buckets, a VersionID. Defaults to "HEAD", which also means the latest +version in an S3 bucket.} \item{repo}{The repository to get the file from. This can be a local git -directory, a GitHub repository (URL or "owner/repo" string), or an S3 bucket -indicated by "s3://bucket-name". Defaults to the current working directory.} +directory, a GitHub repository (URL or \code{"owner/repo"} string), or an S3 +bucket indicated by "s3://bucket-name". Defaults to the current working +directory.} + +\item{store}{Path to the targets store within the project. Defaults to +\verb{"_targets}, or the current project's \link[targets:tar_path_store]{store name} if \code{repo = "."}.} \item{endpoint, region}{For S3 buckets, the endpoint and region of the bucket.} \item{...}{Arguments passed to \code{\link[targets:tar_meta]{targets::tar_meta()}}} } \value{ -A data frame with one row per target/object. See \code{\link[targets:tar_meta]{targets::tar_meta()}} for details. +A data frame with one row per target/object. See +\code{\link[targets:tar_meta]{targets::tar_meta()}} for details. } \description{ -This function extracts \link[targets:tar_meta]{targets metadata} from versioned history. -In most cases this is a git repository, but it can also be an S3 cloud bucket -for a project using cloud versioning and storing the metadata file in the cloud. -(See \code{repository_meta} in \code{\link[targets:tar_option_set]{targets::tar_option_set()}}). +This function extracts \link[targets:tar_meta]{targets metadata} from versioned +history. In most cases this is a git repository, but it can also be an S3 +cloud bucket for a project using cloud versioning and storing the metadata +file in the cloud. (See \code{repository_meta} in \code{\link[targets:tar_option_set]{targets::tar_option_set()}}). } diff --git a/man/tar_read_version.Rd b/man/tar_read_version.Rd index b3dcf03..36695a1 100644 --- a/man/tar_read_version.Rd +++ b/man/tar_read_version.Rd @@ -5,44 +5,44 @@ \alias{tar_read_raw_version} \title{Read a target's value from a git repository} \usage{ -tar_read_version( - name, - ref = "HEAD", - repo = ".", - store = targets::tar_path_store() -) +tar_read_version(name, ref = "HEAD", repo = ".", store = NULL) tar_read_raw_version(name, ref = "HEAD", repo = ".", store = NULL) } \arguments{ -\item{name}{Name of the target. \code{tar_read_version()} can take a symbol, \code{tar_read_raw_version()} requires a character.} +\item{name}{Name of the target. \code{tar_read_version()} can take a symbol, +\code{tar_read_raw_version()} requires a character.} \item{ref}{A git commit SHA, tag, branch or other \href{https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions}{revision string}: -such as "HEAD~1", "main@{2023-02-26 18:30:00}", or "branch@{yesterday}". -Can also be a \code{\link[git2r:commit]{git2r::commit()}} object. For S3 buckets, a VersionID. -Defaults to "HEAD", which also means the latest version in an S3 bucket.} +such as \code{"HEAD~1"}, \code{"main@{2023-02-26 18:30:00}"}, or +\code{"branch@{yesterday}"}. Can also be a \code{\link[git2r:commit]{git2r::commit()}} object. For S3 +buckets, a VersionID. Defaults to "HEAD", which also means the latest +version in an S3 bucket.} \item{repo}{The repository to get the file from. This can be a local git -directory, a GitHub repository (URL or "owner/repo" string), or an S3 bucket -indicated by "s3://bucket-name". Defaults to the current working directory.} +directory, a GitHub repository (URL or \code{"owner/repo"} string), or an S3 +bucket indicated by "s3://bucket-name". Defaults to the current working +directory.} -\item{store}{Path to the targets store within the project. Defaults to \verb{"_targets}, or the current project's \link[targets:tar_path_store]{store name} if \code{repo = "."}.} +\item{store}{Path to the targets store within the project. Defaults to +\verb{"_targets}, or the current project's \link[targets:tar_path_store]{store name} if \code{repo = "."}.} } \value{ -The target's value. If the target is of \code{format = "file"}, this will be the path to the file in the \link[=relic_cache]{relic cache}. +The target's value. If the target is of \code{format = "file"}, this will +be the path to the file in the \link[=relic_cache]{relic cache}. } \description{ -Reads the content of targets from a git repository. Target metadata and -local target files are extracted into a temporary directory before being -read in by \code{tar_read()}. For targets of type "file", the files are also -extracted and the paths to the extracted files are returned. +Reads the content of targets from a git repository. Target metadata and local +target files are extracted into a temporary directory before being read in by +\code{tar_read()}. For targets of type "file", the files are also extracted and +the paths to the extracted files are returned. } \details{ -For cloud targets, the target metadata is read from git history and then -this metadata is used to download the target from the cloud. For this to work, +For cloud targets, the target metadata is read from git history and then this +metadata is used to download the target from the cloud. For this to work, cloud storage must be set up with versioning. Note that targets metadata -includes the bucket, endpoint, and region of a S3-stored target, but you must still -provide an AWS access key and secret as environment variables. If these differ -from the credentials used for your current project or environment, can use -\code{\link[withr:with_envvar]{withr::with_envvar()}} to temporarily set the credentials. +includes the bucket, endpoint, and region of a S3-stored target, but you must +still provide an AWS access key and secret as environment variables. If these +differ from the credentials used for your current project or environment, can +use \code{\link[withr:with_envvar]{withr::with_envvar()}} to temporarily set the credentials. }