diff --git a/.Rbuildignore b/.Rbuildignore new file mode 100644 index 0000000..c7bbae6 --- /dev/null +++ b/.Rbuildignore @@ -0,0 +1,4 @@ +^noclocksrtools\.Rproj$ +^\.Rproj\.user$ +^dev$ +^examples$ diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5b6a065 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +.Rproj.user +.Rhistory +.RData +.Ruserdata diff --git a/DESCRIPTION b/DESCRIPTION new file mode 100644 index 0000000..0053408 --- /dev/null +++ b/DESCRIPTION @@ -0,0 +1,31 @@ +Package: noclocksrtools +Title: Internal Development R Tools for No Clocks, LLC +Version: 0.0.0.9000 +Authors@R: c( + person("Jimmy", "Briggs", , "jimmy.briggs@noclocks.dev", role = c("aut", "cre"), + comment = c(ORCID = "0000-0002-7489-8787")), + person("Patrick", "Howard", , "patrick.howard@noclocks.dev", role = c("aut", "rev"), + comment = c(ORCID = "0000-0000-0000-0000")), + person("No Clocks, LLC", , , "dev@noclocks.dev", role = c("fnd", "cph")) + ) +Description: A collection of internal development tools for No Clocks, + LLC. +License: MIT + file LICENSE +Imports: + covr, + covrpage, + fs, + gitdown, + glue, + httr2, + jsonlite, + markdown, + pkgdown, + purrr, + rlang, + testdown, + utils +Encoding: UTF-8 +Language: en-US +Roxygen: list(markdown = TRUE) +RoxygenNote: 7.3.2.9000 diff --git a/NAMESPACE b/NAMESPACE new file mode 100644 index 0000000..83feeb9 --- /dev/null +++ b/NAMESPACE @@ -0,0 +1,33 @@ +# Generated by roxygen2: do not edit by hand + +export(build_pkgdown) +export(get_opts) +export(pkg_sys) +export(pkg_sys_assets) +export(pkg_sys_config) +export(pkg_sys_css) +export(pkg_sys_examples) +export(pkg_sys_extdata) +export(pkg_sys_fonts) +export(pkg_sys_img) +export(pkg_sys_js) +export(pkg_sys_logos) +export(pkg_sys_scripts) +export(pkg_sys_scss) +export(pkg_sys_styles) +export(pkg_sys_templates) +export(system_file) +importFrom(covr,package_coverage) +importFrom(covr,report) +importFrom(covrpage,covrpage) +importFrom(fs,dir_create) +importFrom(fs,file_move) +importFrom(gitdown,git_down) +importFrom(glue,glue) +importFrom(jsonlite,fromJSON) +importFrom(markdown,markdownToHTML) +importFrom(pkgdown,build_site) +importFrom(purrr,partial) +importFrom(testdown,test_down) +importFrom(utils,globalVariables) +importFrom(utils,packageVersion) diff --git a/R/pkg_data.R b/R/pkg_data.R new file mode 100644 index 0000000..e69de29 diff --git a/R/pkg_deps.R b/R/pkg_deps.R new file mode 100644 index 0000000..4791b5e --- /dev/null +++ b/R/pkg_deps.R @@ -0,0 +1,25 @@ + +# ------------------------------------------------------------------------ +# +# Title : Package Dependency Functions +# By : Jimmy Briggs +# Date : 2024-08-05 +# +# ------------------------------------------------------------------------ + + +# internal ---------------------------------------------------------------- + + + +# utility ----------------------------------------------------------------- + + + +# package dependencies ---------------------------------------------------- + + + +# system requirements ----------------------------------------------------- + + diff --git a/R/pkg_desc.R b/R/pkg_desc.R new file mode 100644 index 0000000..e69de29 diff --git a/R/pkg_down.R b/R/pkg_down.R new file mode 100644 index 0000000..c10a1a7 --- /dev/null +++ b/R/pkg_down.R @@ -0,0 +1,191 @@ + +# ------------------------------------------------------------------------ +# +# Title : Package Documentation via `pkgdown` +# By : Jimmy Briggs +# Date : 2024-08-05 +# +# ------------------------------------------------------------------------ + + +# build ------------------------------------------------------------------- + +#' No Clocks `pkgdown` +#' +#' @description +#' Build a [pkgdown::pkgdown()] site with additional options to include +#' extra reports. +#' +#' The reports that can be included are: +#' - Test Results Report via [testdown::test_down()] +#' - Test Coverage Results via [covrpage::covrpage()] +#' - Git Reports via [gitdown::git_down()] +#' +#' @param pkg (character) Path to the package in development +#' @param pkgdown_path (character) Relative path inside the package to store +#' the final `pkgdown` site +#' @param assets_path (character) Relative path within the package to store +#' the `pkgdown` assets +#' @param reports (character) Vector of reports to be produced. Must be a subset +#' of `c("testdown","gitdown", "coverage")`. The default is +#' `c("coverage", "testdown", "gitdown")`. +#' @param git_branch_ref (character) Git branch to use. `main' by default +#' @param overwrite_assets (logical) Whether the assets directory should be +#' overwritten. Default is `TRUE`. +#' @param ... Additional arguments to pass to `pkgdown::build_site()` +#' +#' @return A `pkgdown` site in the specified `pkgdown_path` directory +#' +#' @export +#' +#' @importFrom fs dir_create file_move +#' @importFrom pkgdown build_site +#' @importFrom covr package_coverage report +#' @importFrom covrpage covrpage +#' @importFrom testdown test_down +#' @importFrom gitdown git_down +#' @importFrom markdown markdownToHTML +#' @importFrom jsonlite fromJSON +#' @importFrom glue glue +#' +#' @example examples/ex_pkgdown.R +build_pkgdown <- function( + pkg, + pkgdown_path = "pkgdown", + assets_path = "pkgdown/assets", + reports = c("coverage", "testdown", "gitdown"), + git_branch_ref = "main", + overwrite_assets = TRUE, + ... +) { + + reports <- rlang::arg_match(reports, multiple = TRUE) + + if (isTRUE(overwrite)) { unlink(file.path(pkg, assets_path), recursive = TRUE) } + + # initialize navbar report + menu <- list() + if (length(reports) != 0) { + fs::dir_create(file.path(pkg, assets_path)) + } + + # generate covr report in a tmp folder and move it to assets path + if (isTRUE("coverage" %in% reports)) { + if (!requireNamespace("covr", quietly = TRUE)) { + stop( + "{covr} needs to be installed" + ) + } + if (!requireNamespace("DT", quietly = TRUE)) { + stop( + "{DT} needs to be installed" + ) + } + if (!requireNamespace("htmltools", quietly = TRUE)) { + stop( + "{htmltools} needs to be installed" + ) + } + if (!requireNamespace("markdown", quietly = TRUE)) { + stop( + "{markdown} needs to be installed" + ) + } + covr_pkg <- covr::package_coverage( + path = pkg, + install_path = file.path(pkg, "covr") + ) + covr::report( + x = covr_pkg, + file = file.path(assets_path, "coverage", "coverage.html"), + browse = FALSE + ) + + # file_move(file.path(pkg, "coverage"), file.path(assets_path, "coverage")) + menu[[length(menu) + 1]] <- list(text = "coverage", href = "coverage/coverage.html") + # Add coverage explanation + markdown::markdownToHTML( + file = system.file( + "templates/markdown/coverage_report_explanation.md", + package = "noclocksr" + ), + output = file.path(assets_path, "coverage", "codecoverage_explanation.html") + ) + menu[[length(menu) + 1]] <- list( + text = "coverage explained", + href = "coverage/codecoverage_explanation.html" + ) + } + + # generate testdown report in assets path + if (isTRUE("testdown" %in% reports)) { + if (!requireNamespace("testdown", quietly = TRUE)) { + stop( + "{testdown} needs to be installed" + ) + } + + testdown::test_down( + pkg = pkg, + book_path = file.path(assets_path, "testdown"), + open = FALSE + ) + menu[[length(menu) + 1]] <- list(text = "testdown", href = "testdown/index.html") + } + + # generate gitdown report in assets path + if (isTRUE("gitdown" %in% reports)) { + if (!requireNamespace("gitdown", quietly = TRUE)) { + stop( + "{gitdown} needs to be installed" + ) + } + + gitdown::git_down( + repo = pkg, + book_path = file.path(assets_path, "gitdown"), + ref = git_branch_ref, + open = FALSE + ) + homepage <- file.path( + "gitdown", + list.files( + pattern = "^gitbook-for", + file.path(assets_path, "gitdown") + )[1] + ) + menu[[length(menu) + 1]] <- list(text = "gitdown", href = homepage) + } + + # prepare yaml settings to add reports in navbar + yaml_settings <- list( + destination = pkgdown_path, + template = list( + assets = assets_path + ), + navbar = list( + structure = list( + left = c("intro", "reference", "articles", "tutorials", "news", "reports") + ), + components = list( + reports = list( + text = "Reports", + menu = menu + ) + ) + ) + ) + + # build site without preview + pkgdown::build_site( + pkg = pkg, + override = yaml_settings, + preview = FALSE, + devel = TRUE, + install = FALSE, + new_process = TRUE, + ... + ) + + +} diff --git a/R/pkg_env.R b/R/pkg_env.R new file mode 100644 index 0000000..e4483cf --- /dev/null +++ b/R/pkg_env.R @@ -0,0 +1,18 @@ + +# ------------------------------------------------------------------------ +# +# Title : Package Environment +# By : Jimmy Briggs +# Date : 2024-08-05 +# +# ------------------------------------------------------------------------ + +# initialize package environment +.pkgenv <- new.env(parent = emptyenv()) + +# initialize environment variables +.pkgenv$init <- FALSE +.pkgenv$options <- list() +.pkgenv$globals <- list() + +.pkgenv$encryption_key <- NULL diff --git a/R/pkg_globals.R b/R/pkg_globals.R new file mode 100644 index 0000000..114f1f1 --- /dev/null +++ b/R/pkg_globals.R @@ -0,0 +1,21 @@ + +# ------------------------------------------------------------------------ +# +# Title : Package Globals +# By : Jimmy Briggs +# Date : 2024-08-05 +# +# ------------------------------------------------------------------------ + +# internal ---------------------------------------------------------------- + +#' @keywords internal +#' @noRd +#' @importFrom utils globalVariables +.pkg_globals <- function() { + if (getRversion() >= "2.15.1") { + utils::globalVariables(c( + # PACKAGE GLOBALS # + )) + } +} diff --git a/R/pkg_imports.R b/R/pkg_imports.R new file mode 100644 index 0000000..2409270 --- /dev/null +++ b/R/pkg_imports.R @@ -0,0 +1,10 @@ + +# ------------------------------------------------------------------------ +# +# Title : Package Imports +# By : Jimmy Briggs +# Date : 2024-08-05 +# +# ------------------------------------------------------------------------ + + diff --git a/R/pkg_meta.R b/R/pkg_meta.R new file mode 100644 index 0000000..e69de29 diff --git a/R/pkg_onload.R b/R/pkg_onload.R new file mode 100644 index 0000000..2b0883e --- /dev/null +++ b/R/pkg_onload.R @@ -0,0 +1,165 @@ + +# ------------------------------------------------------------------------ +# +# Title : Package onLoad +# By : Jimmy Briggs +# Date : 2024-08-05 +# +# ------------------------------------------------------------------------ + +# onLoad ------------------------------------------------------------------ + +#' @keywords internal +#' @noRd +.onLoad <- function( + libname = find.package("noclocksrtools"), + pkgname = "noclocksrtools" +) { + + # globals ----------------------------------------------------------------- + .pkg_globals() + + # get options ------------------------------------------------------------- + .pkgenv$opts_reset <- options() + # in .onUnload, we will reset these options + + # encryption key ---------------------------------------------------------- + key <- Sys.getenv("NOCLOCKS_ENCRYPTION_KEY") + .pkgenv$encryption_key <- key + + # set options ------------------------------------------------------------- + .setopt("noclocks.useragent", .noclocks_user_agent()) + .setopt("noclocks.quiet", FALSE) + .setopt("noclocks.verbose", FALSE) + .setopt("noclocks.debug", FALSE) + .setopt("noclocks.encryption_key", key) + + # load fonts -------------------------------------------------------------- + # .load_fonts() + # sysfonts::font_add() + +} + +# onAttach ---------------------------------------------------------------- + +#' @keywords internal +#' @noRd +.onAttach <- function( + libname = find.package("noclocksrtools"), + pkgname = "noclocksrtools" +) { + + # get options ------------------------------------------------------------- + # .pkgenv$opts_reset <- options() + # in .onUnload, we will reset these options + + # encryption key ---------------------------------------------------------- + # key <- Sys.getenv("NOCLOCKS_ENCRYPTION_KEY") + # .pkgenv$encryption_key <- key + + # set options ------------------------------------------------------------- + # .setopt("noclocks.useragent", .noclocks_user_agent()) + # .setopt("noclocks.quiet", FALSE) + # .setopt("noclocks.verbose", FALSE) + # .setopt("noclocks.debug", FALSE) + # .setopt("noclocks.encryption_key", key) + + # startup message --------------------------------------------------------- + .pkg_startup_msg() + +} + +# onDetach ---------------------------------------------------------------- + +.onDetach <- function(libpath) { + + # reset options ----------------------------------------------------------- + # options(.pkgenv$reset_opts) + +} + + +# onUnload ---------------------------------------------------------------- + +#' @keywords internal +#' @noRd +.onUnload <- function(libpath) { + + # reset options ----------------------------------------------------------- + # options(.pkgenv$reset_opts) + +} + +# startup message --------------------------------------------------------- + +#' @keywords internal +#' @noRd +#' @importFrom utils packageVersion +#' @importFrom glue glue +.pkg_startup_msg <- function() { + ver <- utils::packageVersion('noclocksrtools') + glue::glue( + .sep = "\n", + "Welcome to the `noclocksrtools` package!", + "This is version {ver}.", + "Please refer to the package documentation for more information." + ) |> + packageStartupMessage() +} + + +# user agent -------------------------------------------------------------- + +#' @keywords internal +#' @noRd +#' @importFrom utils packageVersion +#' @importFrom glue glue +.noclocks_user_agent <- function() { + platform <- .Platform$OS.type + locale <- Sys.getlocale("LC_COLLATE") + tz <- Sys.timezone() + rver <- as.character(paste(R.version$major, R.version$minor, sep = ".")) + pkgver <- as.character(utils::packageVersion('noclocksrtools')) + httr2ver <- as.character(utils::packageVersion('httr2')) + rcurlver <- as.character(utils::packageVersion('curl')) + syscurlver <- as.character(httr2:::curl_system_version()) + glue::glue( + "noclocksrtools/{pkgver}", + "httr2/{httr2ver}", + "curl/{rcurlver}", + "libcurl/{syscurlver}", + "R/{rver}", + "{platform} {locale} {tz}", + .sep = " " + ) +} + + +# set options ------------------------------------------------------------- + +#' @keywords internal +#' @noRd +.setopt <- function(opt_name, opt_value, overwrite = TRUE) { + + curr_opt <- getOption(opt_name) + + if (is.null(curr_opt)) { + .pkgenv$opts_reset[[opt_name]] <- NULL + options(opt_name = opt_value) + return(invisible(NULL)) + } else { + if (curr_opt == opt_value) { + .pkgenv$opts_reset[[opt_name]] <- curr_opt + return(invisible(curr_opt)) + } else { + if (overwrite) { + .pkgenv$opts_reset[[opt_name]] <- curr_opt + options(opt_name = opt_value) + return(invisible(curr_opt)) + } else { + return(invisible(curr_opt)) + } + } + } +} + diff --git a/R/pkg_options.R b/R/pkg_options.R new file mode 100644 index 0000000..2626beb --- /dev/null +++ b/R/pkg_options.R @@ -0,0 +1,58 @@ + +# ------------------------------------------------------------------------ +# +# Title : Package Options +# By : Jimmy Briggs +# Date : 2024-08-05 +# +# ------------------------------------------------------------------------ + +# internal ---------------------------------------------------------------- + +# utility ----------------------------------------------------------------- + +# package options --------------------------------------------------------- + +# initialize package options +.pkgenv$options$init <- function() { + # initialize package options + options(noclocksrtools.encryption_key = NULL) +} + +#' Get Options +#' +#' @description +#' Get package options +#' +#' @param opts A character vector of option names to get. Default is `NULL`, +#' and if left `NULL`, will return all available package options included +#' in `noclocksrtools`. +#' +#' @return A named list of package options +#' +#' @export +#' +#' @examples +#' get_opts() +get_opts <- function(opts = NULL) { + if (is.null(opts)) { + opt_names <- grep("^noclocks\\.", names(options()), value = TRUE) + opts <- sapply(opt_names, function(x) { + x <- gsub("^noclocks\\.", "", x) + x <- gsub("\\.", "_", x) + x + }) + names(opts) <- opt_names + } else { + opts <- grep("^noclocks\\.", opts, value = TRUE) + opts <- sapply(opts, function(x) { + x <- gsub("^noclocks\\.", "", x) + x <- gsub("\\.", "_", x) + x + }) + } + + return(opts) + +} + diff --git a/R/pkg_roxy.R b/R/pkg_roxy.R new file mode 100644 index 0000000..be3902e --- /dev/null +++ b/R/pkg_roxy.R @@ -0,0 +1,90 @@ + +# ------------------------------------------------------------------------ +# +# Title : Shared Roxygen +# By : Jimmy Briggs +# Date : 2024-08-05 +# +# ------------------------------------------------------------------------ + +# parameters -------------------------------------------------------------- + +#' Shared Parameters +#' +#' @name .roxy_params +#' +#' @description +#' Reused parameter definitions are gathered here for easier editing. +#' +#' @param req An API request object represented via [httr2::request()]. +#' @param res An API response object represented via [httr2::response()]. +#' +#' @param input,output,session R Shiny Server default function parameters. +#' +#' @param pkg Character representing the package name. +#' +#' @param path Character path to the file or directory. +#' +#' @param id Character representing the unique identifier. +#' +#' @param data `data.frame` or `tibble` object. +#' +#' @param verbose Logical indicating if verbose output should be printed. +#' @param quiet Logical indicating if output should be suppressed. +#' +#' @param ... Additional parameters passed to the function. +#' +#' @keywords internal +#' +#' @noRd +NULL + + +# returns ----------------------------------------------------------------- + +#' Shared Return for an API Request Object +#' +#' @name .roxy_return_api_req +#' +#' @return API request object return from [httr2::request()]. +#' +#' @keywords internal +#' +#' @noRd +NULL + + +#' Shared Return for an API Response Object +#' +#' @name .roxy_return_api_resp +#' +#' @return API response object return from [httr2::response()]. +#' +#' @keywords internal +#' +#' @noRd +NULL + +# pkg_sys ----------------------------------------------------------------- + +#' Re-Used Parameters for Package System Functions +#' +#' @name .pkg_sys_params +#' @keywords internal +#' +#' @param ... A character vector of path components passed to [base::system.file()]. +#' @param pkg (Optional) The package name used to access the system files for. +#' +#' @noRd +NULL + + +#' Re-Used Return Values for Package System Functions +#' +#' @name .pkg_sys_returns +#' @keywords internal +#' +#' @return Character path to the specified system file. +#' +#' @noRd +NULL diff --git a/R/pkg_sys.R b/R/pkg_sys.R new file mode 100644 index 0000000..338d01f --- /dev/null +++ b/R/pkg_sys.R @@ -0,0 +1,230 @@ + +# ------------------------------------------------------------------------ +# +# Title : Package System Resources +# By : Jimmy Briggs +# Date : 2024-08-05 +# +# ------------------------------------------------------------------------ + + +# internal ---------------------------------------------------------------- + +.pkg_assets <- function() { + list( + "images" = list( + "logos" = "images/logos", + "icons" = "images/icons", + "banners" = "images/banners", + "favicons" = "images/favicons", + "team" = "images/team" + ), + "scripts" = list( + "js" = "scripts/js", + "ts" = "scripts/ts" + ), + "styles" = list( + "css" = "styles/css", + "scss" = "styles/scss" + ), + "fonts" = list( + "inter" = "fonts/Inter", + "roboto" = "fonts/Roboto", + "fira" = "fonts/FiraCode" + ), + "html" = list( + "templates" = "html/templates", + "partials" = "html/partials", + "layouts" = "html/layouts" + ), + "animations" = "animations" + ) + +} + +# system_file ------------------------------------------------------------- + +#' System File +#' +#' @description +#' This function is actually a [purrr::partial()] which re-implements +#' [base::system.file()] to be pre-configured to access files from this +#' package: `noclocksrtools`. +#' +#' @inheritParams .pkg_sys_params +#' +#' @section Implementation: +#' This function is implemented using [purrr::partial()] to create a partial +#' function which wraps [base::system.file()] and sets the `package` argument +#' to `noclocksrtools`. +#' +#' @seealso +#' - [pkg_sys()] +#' - [purrr::partial()] +#' - [base::system.file()], [fs::path_package()] +#' +#' @export +#' +#' @inherit .pkg_sys_returns return +#' +#' @keywords internal +#' +#' @family Package Utilities +#' +#' @importFrom purrr partial +system_file <- purrr::partial(.f = system.file, package = "noclocksrtools") + + +# pkg_sys ----------------------------------------------------------------- + +#' Package System File +#' +#' @name pkg_sys +#' +#' @description +#' This function is used to access system files within the package and wraps +#' [base::system.file()] to provide a more convenient interface for accessing +#' and retrieving installed package system files and resources. +#' +#' @inheritParams .pkg_sys_params +#' +#' @export +#' +#' @seealso +#' - [system_file()], [pkg_docs()], [pkg_manual()] +#' - [base::system.file()], [fs::path_package()] +#' +#' @inherit .pkg_sys_returns return +#' +#' @inheritSection pkg_sys_ext Extensions +#' +#' @export +#' +#' @example examples/ex_pkg_sys.R +pkg_sys <- function(...) { + system.file(..., package = "noclocksrtools", mustWork = TRUE) +} + +# extensions -------------------------------------------------------------- + +#' @title Package System Extensions +#' +#' @name pkg_sys_ext +#' +#' @section Extensions: +#' +#' `noclocksrtools` also includes a variety of convenience *extension function* +#' which wrap `pkg_sys()` to access specific directories or types of package +#' resources. +#' +#' ## External Data +#' +#' - `pkg_sys_extdata()`: Access package data files in the `extdata/` external data folder. +#' +#' ## Templates +#' +#' - `pkg_sys_templates()`: Access package templates in the `inst/templates` folder. +#' +#' ## Scripts +#' +#' - `pkg_sys_scripts()`: Access package scripts in the `inst/scripts` folder. +#' +#' ## Configuration +#' +#' - `pkg_sys_config()`: Access package configuration files in the `inst/config` folder. +#' +#' ## Documentation +#' +#' - `pkg_sys_docs()`: Access package documentation files in the `inst/docs` folder. +#' +#' There is also the functions [pkg_docs()] and [pkg_manual()] which launch +#' the package's locally installed documentation website (via `pkgdown`) and +#' its manual PDF, respectively. +#' +#' ## Examples +#' +#' - `pkg_sys_examples()`: Access package example files in the `inst/examples` folder. +#' +#' ## Assets +#' +#' - `pkg_sys_assets()`: Access package assets included in the `assets/` folder. +NULL + +#' @rdname pkg_sys +#' @export +pkg_sys_assets <- function(..., pkg = "noclocksrtools") { + pkg_sys("assets", ..., pkg = pkg) +} + +#' @rdname pkg_sys +#' @export +pkg_sys_img <- function(..., pkg = "noclocksrtools") { + pkg_sys("assets", "images", ..., pkg = pkg) +} + +#' @rdname pkg_sys +#' @export +pkg_sys_scripts <- function(..., pkg = "noclocksrtools") { + pkg_sys("assets", "scripts", ..., pkg = pkg) +} + +#' @rdname pkg_sys +#' @export +pkg_sys_js <- pkg_sys_scripts + +#' @rdname pkg_sys +#' @export +pkg_sys_styles <- function(..., pkg = "noclocksrtools") { + pkg_sys("assets", "styles", ..., pkg = pkg) +} + +#' @rdname pkg_sys +#' @export +pkg_sys_css <- function(..., pkg = "noclocksrtools") { + pkg_sys("assets", "styles", "css", ..., pkg = pkg) +} + +#' @rdname pkg_sys +#' @export +pkg_sys_scss <- function(..., pkg = "noclocksrtools") { + pkg_sys("assets", "styles", "scss", ..., pkg = pkg) +} + +#' @rdname pkg_sys +#' @export +pkg_sys_fonts <- function(..., pkg = "noclocksrtools") { + pkg_sys("assets", "fonts", ..., pkg = pkg) +} + +#' @rdname pkg_sys +#' @export +pkg_sys_logos <- function(..., pkg = "noclocksrtools") { + pkg_sys("assets", "logos", ..., pkg = pkg) +} + +#' @rdname pkg_sys +#' @export +pkg_sys_config <- function(..., pkg = "noclocksrtools") { + pkg_sys("config", ..., pkg = pkg) +} + +#' @rdname pkg_sys +#' @export +pkg_sys_extdata <- function(..., pkg = "noclocksrtools") { + pkg_sys("extdata", ..., pkg = pkg) +} + +#' @rdname pkg_sys +#' @export +pkg_sys_examples <- function(..., pkg = "noclocksrtools") { + pkg_sys("examples", ..., pkg = pkg) +} + +#' @rdname pkg_sys +#' @export +pkg_sys_templates <- function(..., pkg = "noclocksrtools") { + pkg_sys("templates", ..., pkg = pkg) +} + + + diff --git a/dev/config_attachment.yaml b/dev/config_attachment.yaml new file mode 100644 index 0000000..46e24ec --- /dev/null +++ b/dev/config_attachment.yaml @@ -0,0 +1,12 @@ +path.n: NAMESPACE +path.d: DESCRIPTION +dir.r: R +dir.v: vignettes +dir.t: tests +extra.suggests: ~ +pkg_ignore: ~ +document: yes +normalize: yes +inside_rmd: no +must.exist: yes +check_if_suggests_is_installed: yes diff --git a/dev/pkgdevt.R b/dev/pkgdevt.R new file mode 100644 index 0000000..6383154 --- /dev/null +++ b/dev/pkgdevt.R @@ -0,0 +1,41 @@ + +# ------------------------------------------------------------------------ +# +# Title : noclocksrtools - Package Development +# By : Jimmy Briggs +# Date : 2024-08-05 +# +# ------------------------------------------------------------------------ + + +# library ----------------------------------------------------------------- + +require(usethis) + + +# initialize -------------------------------------------------------------- + +usethis::create_package("noclocksrtools") + +usethis::use_build_ignore("dev") +usethis::use_build_ignore("examples") +usethis::use_build_ignore("tools") + +usethis::use_author( + "Jimmy", "Briggs", + role = c("aut", "cre"), + email = "jimmy.briggs@noclocks.dev", + comment = c(ORCID = "0000-0002-7489-8787") +) +usethis::use_author( + "Patrick", "Howard", + role = c("aut", "rev"), + email = "patrick.howard@noclocks.dev", + comment = c(ORCID = "0000-0000-0000-0000") +) +usethis::use_author( + "No Clocks, LLC", + role = c("fnd", "cph"), + email = "dev@noclocks.dev" +) +desc::desc_normalize() diff --git a/examples/ex_pkg_sys.R b/examples/ex_pkg_sys.R new file mode 100644 index 0000000..e349420 --- /dev/null +++ b/examples/ex_pkg_sys.R @@ -0,0 +1,19 @@ +# pkg_sys examples + +# Access the package DESCRIPTION file +pkg_sys("DESCRIPTION") + +# Access the package NAMESPACE file +pkg_sys("NAMESPACE") + +# Access External Data +pkg_sys("extdata", "data.csv") +# or +pkg_sys_extdata("data.csv") + +# Access Assets +pkg_sys("assets", "images", "logo.png") +# or +pkg_sys_assets("images", "logo.png") +# or +pkg_sys_img("logo.png") diff --git a/examples/ex_pkgdown.R b/examples/ex_pkgdown.R new file mode 100644 index 0000000..36d4b9c --- /dev/null +++ b/examples/ex_pkgdown.R @@ -0,0 +1,9 @@ +if (FALSE) { + # build a noclocks pkgdown site with extra reports: + build_pkgdown_with_reports( + pkg = ".", + pkgdown_path = "public", + assets_path = "pkgdown/assets", + reports = c("testdown","coverage") + ) +} diff --git a/man/build_pkgdown.Rd b/man/build_pkgdown.Rd new file mode 100644 index 0000000..ffe484e --- /dev/null +++ b/man/build_pkgdown.Rd @@ -0,0 +1,61 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/pkg_down.R +\name{build_pkgdown} +\alias{build_pkgdown} +\title{No Clocks \code{pkgdown}} +\usage{ +build_pkgdown( + pkg, + pkgdown_path = "pkgdown", + assets_path = "pkgdown/assets", + reports = c("coverage", "testdown", "gitdown"), + git_branch_ref = "main", + overwrite_assets = TRUE, + ... +) +} +\arguments{ +\item{pkg}{(character) Path to the package in development} + +\item{pkgdown_path}{(character) Relative path inside the package to store +the final \code{pkgdown} site} + +\item{assets_path}{(character) Relative path within the package to store +the \code{pkgdown} assets} + +\item{reports}{(character) Vector of reports to be produced. Must be a subset +of \code{c("testdown","gitdown", "coverage")}. The default is +\code{c("coverage", "testdown", "gitdown")}.} + +\item{git_branch_ref}{(character) Git branch to use. `main' by default} + +\item{overwrite_assets}{(logical) Whether the assets directory should be +overwritten. Default is \code{TRUE}.} + +\item{...}{Additional arguments to pass to \code{pkgdown::build_site()}} +} +\value{ +A \code{pkgdown} site in the specified \code{pkgdown_path} directory +} +\description{ +Build a \code{\link[pkgdown:pkgdown-package]{pkgdown::pkgdown()}} site with additional options to include +extra reports. + +The reports that can be included are: +\itemize{ +\item Test Results Report via \code{\link[testdown:test_down]{testdown::test_down()}} +\item Test Coverage Results via \code{\link[covrpage:covrpage]{covrpage::covrpage()}} +\item Git Reports via \code{\link[gitdown:git_down]{gitdown::git_down()}} +} +} +\examples{ +if (FALSE) { + # build a noclocks pkgdown site with extra reports: + build_pkgdown_with_reports( + pkg = ".", + pkgdown_path = "public", + assets_path = "pkgdown/assets", + reports = c("testdown","coverage") + ) +} +} diff --git a/man/get_opts.Rd b/man/get_opts.Rd new file mode 100644 index 0000000..e4e830f --- /dev/null +++ b/man/get_opts.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/pkg_options.R +\name{get_opts} +\alias{get_opts} +\title{Get Options} +\usage{ +get_opts(opts = NULL) +} +\arguments{ +\item{opts}{A character vector of option names to get. Default is \code{NULL}, +and if left \code{NULL}, will return all available package options included +in \code{noclocksrtools}.} +} +\value{ +A named list of package options +} +\description{ +Get package options +} +\examples{ +get_opts() +} diff --git a/man/pkg_sys.Rd b/man/pkg_sys.Rd new file mode 100644 index 0000000..35c67da --- /dev/null +++ b/man/pkg_sys.Rd @@ -0,0 +1,132 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/pkg_sys.R +\name{pkg_sys} +\alias{pkg_sys} +\alias{pkg_sys_assets} +\alias{pkg_sys_img} +\alias{pkg_sys_scripts} +\alias{pkg_sys_js} +\alias{pkg_sys_styles} +\alias{pkg_sys_css} +\alias{pkg_sys_scss} +\alias{pkg_sys_fonts} +\alias{pkg_sys_logos} +\alias{pkg_sys_config} +\alias{pkg_sys_extdata} +\alias{pkg_sys_examples} +\alias{pkg_sys_templates} +\title{Package System File} +\usage{ +pkg_sys(...) + +pkg_sys_assets(..., pkg = "noclocksrtools") + +pkg_sys_img(..., pkg = "noclocksrtools") + +pkg_sys_scripts(..., pkg = "noclocksrtools") + +pkg_sys_js(..., pkg = "noclocksrtools") + +pkg_sys_styles(..., pkg = "noclocksrtools") + +pkg_sys_css(..., pkg = "noclocksrtools") + +pkg_sys_scss(..., pkg = "noclocksrtools") + +pkg_sys_fonts(..., pkg = "noclocksrtools") + +pkg_sys_logos(..., pkg = "noclocksrtools") + +pkg_sys_config(..., pkg = "noclocksrtools") + +pkg_sys_extdata(..., pkg = "noclocksrtools") + +pkg_sys_examples(..., pkg = "noclocksrtools") + +pkg_sys_templates(..., pkg = "noclocksrtools") +} +\description{ +This function is used to access system files within the package and wraps +\code{\link[base:system.file]{base::system.file()}} to provide a more convenient interface for accessing +and retrieving installed package system files and resources. +} +\section{Extensions}{ + + +\code{noclocksrtools} also includes a variety of convenience \emph{extension function} +which wrap \code{pkg_sys()} to access specific directories or types of package +resources. +\subsection{External Data}{ +\itemize{ +\item \code{pkg_sys_extdata()}: Access package data files in the \verb{extdata/} external data folder. +} +} + +\subsection{Templates}{ +\itemize{ +\item \code{pkg_sys_templates()}: Access package templates in the \code{inst/templates} folder. +} +} + +\subsection{Scripts}{ +\itemize{ +\item \code{pkg_sys_scripts()}: Access package scripts in the \code{inst/scripts} folder. +} +} + +\subsection{Configuration}{ +\itemize{ +\item \code{pkg_sys_config()}: Access package configuration files in the \code{inst/config} folder. +} +} + +\subsection{Documentation}{ +\itemize{ +\item \code{pkg_sys_docs()}: Access package documentation files in the \code{inst/docs} folder. +} + +There is also the functions \code{\link[=pkg_docs]{pkg_docs()}} and \code{\link[=pkg_manual]{pkg_manual()}} which launch +the package's locally installed documentation website (via \code{pkgdown}) and +its manual PDF, respectively. +} + +\subsection{Examples}{ +\itemize{ +\item \code{pkg_sys_examples()}: Access package example files in the \code{inst/examples} folder. +} +} + +\subsection{Assets}{ +\itemize{ +\item \code{pkg_sys_assets()}: Access package assets included in the \verb{assets/} folder. +} +} +} + +\examples{ +# pkg_sys examples + +# Access the package DESCRIPTION file +pkg_sys("DESCRIPTION") + +# Access the package NAMESPACE file +pkg_sys("NAMESPACE") + +# Access External Data +pkg_sys("extdata", "data.csv") +# or +pkg_sys_extdata("data.csv") + +# Access Assets +pkg_sys("assets", "images", "logo.png") +# or +pkg_sys_assets("images", "logo.png") +# or +pkg_sys_img("logo.png") +} +\seealso{ +\itemize{ +\item \code{\link[=system_file]{system_file()}}, \code{\link[=pkg_docs]{pkg_docs()}}, \code{\link[=pkg_manual]{pkg_manual()}} +\item \code{\link[base:system.file]{base::system.file()}}, \code{\link[fs:path_package]{fs::path_package()}} +} +} diff --git a/man/pkg_sys_ext.Rd b/man/pkg_sys_ext.Rd new file mode 100644 index 0000000..07272d9 --- /dev/null +++ b/man/pkg_sys_ext.Rd @@ -0,0 +1,61 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/pkg_sys.R +\name{pkg_sys_ext} +\alias{pkg_sys_ext} +\title{Package System Extensions} +\description{ +Package System Extensions +} +\section{Extensions}{ + + +\code{noclocksrtools} also includes a variety of convenience \emph{extension function} +which wrap \code{pkg_sys()} to access specific directories or types of package +resources. +\subsection{External Data}{ +\itemize{ +\item \code{pkg_sys_extdata()}: Access package data files in the \verb{extdata/} external data folder. +} +} + +\subsection{Templates}{ +\itemize{ +\item \code{pkg_sys_templates()}: Access package templates in the \code{inst/templates} folder. +} +} + +\subsection{Scripts}{ +\itemize{ +\item \code{pkg_sys_scripts()}: Access package scripts in the \code{inst/scripts} folder. +} +} + +\subsection{Configuration}{ +\itemize{ +\item \code{pkg_sys_config()}: Access package configuration files in the \code{inst/config} folder. +} +} + +\subsection{Documentation}{ +\itemize{ +\item \code{pkg_sys_docs()}: Access package documentation files in the \code{inst/docs} folder. +} + +There is also the functions \code{\link[=pkg_docs]{pkg_docs()}} and \code{\link[=pkg_manual]{pkg_manual()}} which launch +the package's locally installed documentation website (via \code{pkgdown}) and +its manual PDF, respectively. +} + +\subsection{Examples}{ +\itemize{ +\item \code{pkg_sys_examples()}: Access package example files in the \code{inst/examples} folder. +} +} + +\subsection{Assets}{ +\itemize{ +\item \code{pkg_sys_assets()}: Access package assets included in the \verb{assets/} folder. +} +} +} + diff --git a/man/system_file.Rd b/man/system_file.Rd new file mode 100644 index 0000000..3df729e --- /dev/null +++ b/man/system_file.Rd @@ -0,0 +1,29 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/pkg_sys.R +\name{system_file} +\alias{system_file} +\title{System File} +\usage{ +system_file(...) +} +\description{ +This function is actually a \code{\link[purrr:partial]{purrr::partial()}} which re-implements +\code{\link[base:system.file]{base::system.file()}} to be pre-configured to access files from this +package: \code{noclocksrtools}. +} +\section{Implementation}{ + +This function is implemented using \code{\link[purrr:partial]{purrr::partial()}} to create a partial +function which wraps \code{\link[base:system.file]{base::system.file()}} and sets the \code{package} argument +to \code{noclocksrtools}. +} + +\seealso{ +\itemize{ +\item \code{\link[=pkg_sys]{pkg_sys()}} +\item \code{\link[purrr:partial]{purrr::partial()}} +\item \code{\link[base:system.file]{base::system.file()}}, \code{\link[fs:path_package]{fs::path_package()}} +} +} +\concept{Package Utilities} +\keyword{internal} diff --git a/noclocksrtools.Rproj b/noclocksrtools.Rproj new file mode 100644 index 0000000..766b3b2 --- /dev/null +++ b/noclocksrtools.Rproj @@ -0,0 +1,22 @@ +Version: 1.0 + +RestoreWorkspace: No +SaveWorkspace: No +AlwaysSaveHistory: Default + +EnableCodeIndexing: Yes +UseSpacesForTab: Yes +NumSpacesForTab: 2 +Encoding: UTF-8 + +RnwWeave: knitr +LaTeX: pdfLaTeX + +AutoAppendNewline: Yes +StripTrailingWhitespace: Yes +LineEndingConversion: Posix + +BuildType: Package +PackageUseDevtools: Yes +PackageInstallArgs: --no-multiarch --with-keep.source +PackageRoxygenize: rd,collate,namespace