From 98360b9cbcd0a52654807f9f0627791d10d7ed60 Mon Sep 17 00:00:00 2001 From: Maximilian Held Date: Thu, 18 Feb 2021 18:35:03 +0100 Subject: [PATCH 1/4] reduce lint preparing for #16 --- R/github.R | 5 +++-- R/helpers.R | 28 +++++++++++++++++----------- R/pkgdown.R | 30 +++++++++++++++--------------- R/setup.R | 13 ++++++++----- R/test-helpers.R | 6 +++--- R/testing.R | 10 ++++++---- man/is_github_actions.Rd | 3 ++- man/use_codecov2.Rd | 3 ++- 8 files changed, 56 insertions(+), 42 deletions(-) diff --git a/R/github.R b/R/github.R index 804755c..3664c3a 100644 --- a/R/github.R +++ b/R/github.R @@ -28,7 +28,8 @@ gh_pkgs_image_url <- function(image_name = gh_pkgs_image_name(target = "runtime" ) } -#' @describeIn gh_pkgs_image_url Get the docker image name conventionally used in muggle projects +#' @describeIn gh_pkgs_image_url +#' Get the docker image name conventionally used in muggle projects #' #' @param target Build target for multistage muggle builds. #' By convention, for a package `foo`, {muggle} would build a `foo-buildtime` and `foo-runtime` for the `buildtime` and `runtime` docker multistage build targets, respectively. @@ -64,7 +65,7 @@ gh_pkgs_image_version <- function() { gh_repo_spec <- function() { # something like this already exists in usethis, but seems unexported # muggle image *has* git, and on gh actions should also have a repo - # but this will not work in a local docker container, which has git, but no repo + # but this will not work in a local docker cont, which has git, but no repo do.call(paste, c(gh::gh_tree_remote(), sep = "/")) } diff --git a/R/helpers.R b/R/helpers.R index 591f8f2..f8c49a0 100644 --- a/R/helpers.R +++ b/R/helpers.R @@ -1,6 +1,7 @@ #' Browse to URL #' -#' @details This function is copied from an unexported function in [usethis](https://github.com/r-lib/usethis/blob/23dd62c5e7713ed8ecceae82e6338f795d30ba92/R/helpers.R). +#' @details +#' This function is copied from an unexported function in [usethis](https://github.com/r-lib/usethis/blob/23dd62c5e7713ed8ecceae82e6338f795d30ba92/R/helpers.R). #' #' @param ... Elements of the URL #' @param open `[logical(1)]` giving whether the URL should be opened @@ -24,17 +25,18 @@ remove_dep <- function(x) { desc::desc_del_dep(x) usethis::ui_done( x = glue::glue( - "Removing {dep} from DESCRIPTION again, because it is already included in the muggle image.", + "Removing {dep} from DESCRIPTION again, ", + "because it is already included in the muggle image.", dep = x ) ) } #' Muggle files -#' -#' @param muggle_file +#' +#' @param muggle_file #' File to copy, relative path from built package root. -#' +#' #' @keywords internal #' @export get_muggle_file <- function(muggle_file) { @@ -42,16 +44,16 @@ get_muggle_file <- function(muggle_file) { } #' Temporarily get muggle files -#' +#' #' Copies muggle files ([get_muggle_file()]) to the working directory. #' Files are deleted when `.local_envir` expires. #' If file already exists, only a warning is thrown. #' Useful to avoid pasting boilerplate files in muggle packages. -#' +#' #' @inheritParams get_muggle_file -#' +#' #' @inheritParams withr::local_file -#' +#' #' @keywords internal #' @export local_muggle_file <- function(muggle_file, .local_envir = parent.frame()) { @@ -62,14 +64,18 @@ local_muggle_file <- function(muggle_file, .local_envir = parent.frame()) { "To use muggle defaults, remove the file." )) } else { - target <- withr::local_file(.file = muggle_file, .local_envir = .local_envir) + target <- withr::local_file( + .file = muggle_file, + .local_envir = .local_envir + ) fs::file_copy(path = get_muggle_file(muggle_file), new_path = target) } } #' Determine if code is running inside GitHub Actions #' -#' Looks for the `GITHUB_ACTIONS` environment variable, as [documented](https://docs.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables) +#' Looks for the `GITHUB_ACTIONS` environment variable, +#' as [documented](https://docs.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables) #' #' @keywords internal is_github_actions <- function() { diff --git a/R/pkgdown.R b/R/pkgdown.R index 82079ef..376dc63 100644 --- a/R/pkgdown.R +++ b/R/pkgdown.R @@ -1,8 +1,8 @@ #' Replacement versions of [pkgdown::build_site()] etc. with muggle defaults -#' +#' #' Sets some muggle defaults for pkgdown to minimize code duplication across muggle projects. #' This includes overrides of `_pkgdown.yml` and `_site.yml`. -#' +#' #' @section Additions to pkgdown: #' These replacement versions of pkgdown functions make the following changes to pkgdown, as applicable: #' - If there are `vignettes/`, declaring a default vignette rendering function ([local_siteyaml()]) @@ -10,7 +10,7 @@ #' Be careful not to provide conflicting overrides. #' - Sets `run_dont_run = TRUE`, so that examples inside `\dontrun{}` are still run inside of pkgdown. #' Examples often need to be skipped on CRAN and other checks, though not when building pkgdown. -#' +#' #' @inheritSection pkgdown::build_site YAML config - navbar #' @inheritParams pkgdown::build_site #' @inheritDotParams pkgdown::build_site @@ -40,12 +40,12 @@ build_article2 <- function(...) { } #' List of overrides for `_pkgdown.yml` with muggle defaults. -#' +#' #' @examples #' \dontrun{ #' override_pkgdownyaml() #' } -#' +#' #' @family pkgdown functions #' @export override_pkgdownyaml <- function() { @@ -56,30 +56,30 @@ override_pkgdownyaml <- function() { #' Temporarily create muggle default `vignettes/_site.yml` file -#' +#' #' Upgrades vignettes to muggle default. #' Wraps [local_muggle_file()] to delete file upon use. -#' +#' #' @details #' This `vignettes/_site.yml` declares the default vignette rendering function for muggle vignettes. #' To enable it, you also must declare in the yaml frontmatter *for each of the vignettes*: -#' +#' #' ```yaml #' pkgdown: #' as_is: true #' ``` -#' +#' #' For an example of such a vignette with all its features, see `vignette("vignette-muggle")` -#' +#' #' @section Features: #' ## Backported Bookdown Features #' By default, pkgdown builds vignettes (or rather, articles) using a special format based on [rmarkdown::html_document()]. #' This format does not include the automatic numbering and crossreferencing of figures, tables, equations, and (for cross-references) sections supported by [bookdown](http://bookdown.org). #' The [`bookdown::html_document2()`](https://bookdown.org/yihui/bookdown/a-single-document.html) render function backports these features for uses outside of bookdown. -#' +#' #' ## Raw HTML #' Pandoc extensions are set to allow correctly indented raw HTML inside vignettes. -#' +#' #' @inheritParams local_muggle_file #' @family pkgdown functions #' @export @@ -88,17 +88,17 @@ local_siteyaml <- function(.local_envir = parent.frame()) { } #' Retrieve the public URL from the `DESCRIPTION` -#' +#' #' Chooses whichever URL in the `DESCRIPTION` is *not* on github.com. #' That's assumed to be the public-facing website, such as a pkgdown website on GitHub pages. -#' +#' #' @keywords internal get_url_from_desc <- function() { all_urls <- desc::desc_get_urls() gh_urls <- sapply(all_urls, is_gh_url) public_urls <- all_urls[!gh_urls] public_urls[1] -} +} is_gh_url <- function(url) { httr::parse_url(url)$hostname == "github.com" diff --git a/R/setup.R b/R/setup.R index 9e0398b..492ee7e 100644 --- a/R/setup.R +++ b/R/setup.R @@ -21,7 +21,8 @@ #' #' @inheritParams usethis::create_package #' @param license one of the license functions in [usethis] -#' @param license_holder giving the license holder, used as `cph` and `fnd` role in `DESCRIPTION` +#' @param license_holder +#' giving the license holder, used as `cph` and `fnd` role in `DESCRIPTION` #' @inheritParams usethis::use_github #' @family setup functions #' @export @@ -63,7 +64,8 @@ create_muggle_package <- function(path, usethis::use_git() # imperfect check for whether github remote is set if (nrow(gert::git_remote_list()) == 0) { - # if there was already a git remote as will be the case for existing projects, the whole function would error out here + # if there was already a git remote as will be the case for existing projects, + # the whole function would error out here usethis::use_github( organisation = organisation, private = private, @@ -98,9 +100,10 @@ create_muggle_package <- function(path, text = c("See `help('muggle::lib_cache_path')`"), path = fs::path(lib_cache_path, "README.md") ) - usethis::ui_done( - "Created {usethis::ui_code(lib_cache_path)} to add cached dependencies to docker build context on GitHub actions." - ) + usethis::ui_done(c( + "Created {usethis::ui_code(lib_cache_path)} to add cached dependencies ", + "to docker build context on GitHub actions." + )) # compute environment ==== # TODO add docker generation diff --git a/R/test-helpers.R b/R/test-helpers.R index c596470..64305ae 100644 --- a/R/test-helpers.R +++ b/R/test-helpers.R @@ -1,11 +1,11 @@ local_create_package <- function(dir = fs::file_temp(), env = parent.frame()) { old_wd <- getwd() - + usethis::create_package(dir, open = FALSE) withr::defer(fs::dir_delete(dir), envir = env) - + setwd(dir) withr::defer(setwd(old_wd), envir = env) - + dir } diff --git a/R/testing.R b/R/testing.R index d1d456b..d8f7e12 100644 --- a/R/testing.R +++ b/R/testing.R @@ -1,12 +1,14 @@ #' Set up codecov -#' @param reposlug `[character(1)]` giving the `username/repo` URL slug of the project. +#' @param reposlug `[character(1)]` +#' giving the `username/repo` URL slug of the project. #' @family testing functions #' @export use_codecov2 <- function(reposlug) { usethis::use_coverage(type = "codecov") - usethis::ui_todo( - "Add the {usethis::ui_value('Repository Upload Token')} from codecov as a secret called {usethis::ui_value('CODECOV_TOKEN')} on GitHub." - ) + usethis::ui_todo(c( + "Add the {usethis::ui_value('Repository Upload Token')} from codecov ", + "as a secret called {usethis::ui_value('CODECOV_TOKEN')} on GitHub." + )) view_url("https://codecov.io/gh", reposlug, "settings") view_url("https://github.com", reposlug, "settings", "secrets") } diff --git a/man/is_github_actions.Rd b/man/is_github_actions.Rd index f7ac033..63f217f 100644 --- a/man/is_github_actions.Rd +++ b/man/is_github_actions.Rd @@ -7,6 +7,7 @@ is_github_actions() } \description{ -Looks for the \code{GITHUB_ACTIONS} environment variable, as \href{https://docs.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables}{documented} +Looks for the \code{GITHUB_ACTIONS} environment variable, +as \href{https://docs.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables}{documented} } \keyword{internal} diff --git a/man/use_codecov2.Rd b/man/use_codecov2.Rd index 722de52..2e1f754 100644 --- a/man/use_codecov2.Rd +++ b/man/use_codecov2.Rd @@ -7,7 +7,8 @@ use_codecov2(reposlug) } \arguments{ -\item{reposlug}{\verb{[character(1)]} giving the \code{username/repo} URL slug of the project.} +\item{reposlug}{\verb{[character(1)]} +giving the \code{username/repo} URL slug of the project.} } \description{ Set up codecov From f5f4c96d048ba13255a320e69c8b40c48983b15c Mon Sep 17 00:00:00 2001 From: Maximilian Held Date: Thu, 18 Feb 2021 19:03:37 +0100 Subject: [PATCH 2/4] add superlinter #16 --- .github/workflows/linter.yaml | 55 +++++++++++++++++++++++++++++++++++ NAMESPACE | 1 + R/testing.R | 14 ++++++++- man/use_codecov2.Rd | 6 +++- man/use_superlinter.Rd | 16 ++++++++++ pkgdown/_pkgdown.yml | 6 ++-- 6 files changed, 93 insertions(+), 5 deletions(-) create mode 100644 .github/workflows/linter.yaml create mode 100644 man/use_superlinter.Rd diff --git a/.github/workflows/linter.yaml b/.github/workflows/linter.yaml new file mode 100644 index 0000000..c188ae2 --- /dev/null +++ b/.github/workflows/linter.yaml @@ -0,0 +1,55 @@ +--- +########################### +########################### +## Linter GitHub Actions ## +########################### +########################### +name: Lint Code Base + +# +# Documentation: +# https://help.github.com/en/articles/workflow-syntax-for-github-actions +# + +############################# +# Start the job on all push # +############################# +on: + push: + branches-ignore: [master] + # Remove the line above to run when pushing to master + pull_request: + branches: [master] + +############### +# Set the Job # +############### +jobs: + build: + # Name the Job + name: Lint Code Base + # Set the agent to run on + runs-on: ubuntu-latest + + ################## + # Load all steps # + ################## + steps: + ########################## + # Checkout the code base # + ########################## + - name: Checkout Code + uses: actions/checkout@v2 + with: + # Full git history is needed to get a proper list of changed files within `super-linter` + fetch-depth: 0 + + ################################ + # Run Linter against code base # + ################################ + - name: Lint Code Base + uses: github/super-linter@v3 + env: + VALIDATE_ALL_CODEBASE: false + DEFAULT_BRANCH: master + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/NAMESPACE b/NAMESPACE index eed41f5..67d2a33 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -16,4 +16,5 @@ export(remove_dep) export(use_codecov2) export(use_onbuild_image) export(use_radian) +export(use_superlinter) export(view_url) diff --git a/R/testing.R b/R/testing.R index d8f7e12..a10166e 100644 --- a/R/testing.R +++ b/R/testing.R @@ -1,7 +1,7 @@ #' Set up codecov #' @param reposlug `[character(1)]` #' giving the `username/repo` URL slug of the project. -#' @family testing functions +#' @family quality control functions #' @export use_codecov2 <- function(reposlug) { usethis::use_coverage(type = "codecov") @@ -12,3 +12,15 @@ use_codecov2 <- function(reposlug) { view_url("https://codecov.io/gh", reposlug, "settings") view_url("https://github.com", reposlug, "settings", "secrets") } + +#' Set up [super-linter](https://github.com/github/super-linter) +#' @family quality control functions +#' @export +use_superlinter <- function() { + superlinter_url <- "https://github.com/marketplace/actions/super-linter" + usethis::ui_todo(c( + "Please add the {usethis::ui_code{'linter.yaml'} ", + "as described on {usethis::ui_code{superlinter_url}." + )) + view_url(superlinter_url) +} diff --git a/man/use_codecov2.Rd b/man/use_codecov2.Rd index 2e1f754..2afb780 100644 --- a/man/use_codecov2.Rd +++ b/man/use_codecov2.Rd @@ -13,4 +13,8 @@ giving the \code{username/repo} URL slug of the project.} \description{ Set up codecov } -\concept{testing functions} +\seealso{ +Other quality control functions: +\code{\link{use_superlinter}()} +} +\concept{quality control functions} diff --git a/man/use_superlinter.Rd b/man/use_superlinter.Rd new file mode 100644 index 0000000..c9827f7 --- /dev/null +++ b/man/use_superlinter.Rd @@ -0,0 +1,16 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/testing.R +\name{use_superlinter} +\alias{use_superlinter} +\title{Set up \href{https://github.com/github/super-linter}{super-linter}} +\usage{ +use_superlinter() +} +\description{ +Set up \href{https://github.com/github/super-linter}{super-linter} +} +\seealso{ +Other quality control functions: +\code{\link{use_codecov2}()} +} +\concept{quality control functions} diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 876ce7a..b81ac30 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -28,11 +28,11 @@ reference: Setting up RStudio and vscode. - contents: - has_concept("editor functions") -- subtitle: Testing +- subtitle: Quality Control desc: > - Set up unit testing. + Set up testing and linting. - contents: - - has_concept("testing functions") + - has_concept("quality control functions") - subtitle: Deployment desc: > Deploy muggle projects to the public cloud. From 8f15c35cf1f6d2051be6d9723d8207c6cbf39e66 Mon Sep 17 00:00:00 2001 From: Maximilian Held Date: Thu, 18 Feb 2021 20:20:48 +0100 Subject: [PATCH 3/4] reduce more lint --- R/compute_env.R | 9 +++-- R/deployment.R | 66 +++++++++++++++++++++++++--------- R/github.R | 33 ++++++++++++----- R/helpers.R | 7 ++-- R/pkgdown.R | 44 +++++++++++++++-------- R/setup.R | 35 ++++++++++++------ README.md | 2 -- man/az_webapp_config_muggle.Rd | 58 ++++++++++++++++++++++-------- man/build_site2.Rd | 18 ++++++---- man/create_muggle_package.Rd | 31 +++++++++++----- man/get_url_from_desc.Rd | 3 +- man/gh_pkgs_image_url.Rd | 26 ++++++++++---- man/install_sysdeps.Rd | 3 +- man/is_github_actions.Rd | 4 +-- man/lib_cache_path.Rd | 3 +- man/local_siteyaml.Rd | 23 ++++++++---- man/use_onbuild_image.Rd | 3 +- man/view_url.Rd | 3 +- 18 files changed, 263 insertions(+), 108 deletions(-) diff --git a/R/compute_env.R b/R/compute_env.R index c013b61..32c0f76 100644 --- a/R/compute_env.R +++ b/R/compute_env.R @@ -1,6 +1,7 @@ #' Set up or update the compute environment #' -#' Adds or updates a `Dockerfile` and corresponding `main.yaml` GitHub Actions workflow. +#' Adds or updates a `Dockerfile` +#' and corresponding `main.yaml` GitHub Actions workflow. #' #' @family compute environment functions #' @export @@ -13,7 +14,8 @@ use_onbuild_image <- function() { #' Install System Dependencies #' -#' Infers and installs system dependencies from `DESCRIPTION` via the [r-hub/sysreqs](https://github.com/r-hub/sysreqs) project. +#' Infers and installs system dependencies from `DESCRIPTION` +#' via the [r-hub/sysreqs](https://github.com/r-hub/sysreqs) project. #' #' @family compute environment functions #' @keywords internal @@ -39,7 +41,8 @@ install_sysdeps <- function() { #' Directory for copying dependencies to docker build context #' -#' This directory serves to copy the package cache into the docker build context on GitHub actions. +#' This directory serves to copy the package cache +#' into the docker build context on GitHub actions. #' #' @family compute environment functions #' @keywords internal diff --git a/R/deployment.R b/R/deployment.R index b7827a2..53713db 100644 --- a/R/deployment.R +++ b/R/deployment.R @@ -5,30 +5,58 @@ #' @details Wrapping with muggle defaults; use only inside muggle projects. #' #' @details # Authenticating Against GitHub Packages -#' Because muggle stores the docker images with the shiny runtimes on GitHub Packages, Azure must pull images from there, not the commonly used Docker Hub. +#' Because muggle stores the docker images with the shiny runtimes on +#' GitHub Packages, Azure must pull images from there, +#' not the commonly used Docker Hub. #' -#' Currently, GitHub Packages does not offer public images, even for public repositories ([#133](https://github.com/subugoe/muggle/issues/133)). -#' That means that Azure must be [authenticated](https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages) to be able to download the runtime images. -#' This is the inverse of the the `azure login` GitHub Action, which authenticates the GitHub Actions runtime to talk to Azure. +#' Currently, GitHub Packages does not offer public images, +#' even for public repositories +#' ([#133](https://github.com/subugoe/muggle/issues/133)) +#' That means that Azure must be +#' [authenticated](https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages) +#' to be able to download the runtime images. +#' This is the inverse of the the `azure login` GitHub Action, +#' which authenticates the GitHub Actions runtime to talk to Azure. #' -#' There are (only) two ways to do this, both suboptimal ([#132](https://github.com/subugoe/muggle/issues/132)): +#' There are (only) two ways to do this, +#' both suboptimal ([#132](https://github.com/subugoe/muggle/issues/132)): #' -#' 1. You can authenticate Azure with a [personal access token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) and the corresponding **static GitHub username**. -#' No matter who commits and triggered the deployment, always the same personal GitHub credentials (say, those of Jane Doe) will be used. -#' To do this, the volunteering team member should create a PAT on GitHub, scope it minimally to only read packages, and paste that into the Azure web ui at portal.azure.com. -#' A minimally scoped PAT may be reasonably safe, but the approach is still cumbersome and awkward. -#' 2. You can authenticate Azure towards GitHub Packages **with the `GITHUB_ACTOR` and `GITHUB_TOKEN` pair** [furnished](https://docs.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token) for GitHub Actions, from which the deployment takes place. -#' The `GITHUB_ACTOR` environment variable will always be the GitHub username of whoever triggered the workflow run, and therefore, the deployment. -#' The `GITHUB_TOKEN` is a PAT scoped to *only* that repo and will expire automatically after the workflow run is completed. -#' To use this authentication, use the below defaults and expose the `GITHUB_TOKEN` to in your workflow `*.yaml` file. +#' 1. You can authenticate Azure with a +#' [personal access token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) +#' and the corresponding **static GitHub username**. +#' No matter who commits and triggered the deployment, +#' always the same personal GitHub credentials +#' (say, those of Jane Doe) will be used. +#' To do this, the volunteering team member should create a PAT on GitHub, +#' scope it minimally to only read packages, +#' and paste that into the Azure web ui at portal.azure.com. +#' A minimally scoped PAT may be reasonably safe, +#' but the approach is still cumbersome and awkward. +#' 2. You can authenticate Azure towards GitHub Packages +#' **with the `GITHUB_ACTOR` and `GITHUB_TOKEN` pair** +#' [furnished](https://docs.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token) +#' for GitHub Actions, from which the deployment takes place. +#' The `GITHUB_ACTOR` environment variable will always be +#' the GitHub username of whoever triggered the workflow run, +#' and therefore, the deployment. +#' The `GITHUB_TOKEN` is a PAT scoped to *only* that repo and will expire +#' automatically after the workflow run is completed. +#' To use this authentication, use the below defaults and expose the +#' `GITHUB_TOKEN` to in your workflow `*.yaml` file. #' #' ```yaml #' env: #' GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} #' ``` #' -#' This is a more elegant, and arguably more secure solution, though the `GITHUB_TOKEN` still has more scope than just to read packages, if only for the repo in question. -#' This form of authentication seems to work reliably, but may break future app (re)starts on Azure: Should Azure loose the docker cache of the image in question, it will not be able to `docker pull` the image again, because the `GITHUB_TOKEN` will have expired by then. +#' This is a more elegant, and arguably more secure solution, +#' though the `GITHUB_TOKEN` still has more scope than just to read packages, +#' if only for the repo in question. +#' This form of authentication seems to work reliably, +#' but may break future app (re)starts on Azure: +#' Should Azure loose the docker cache of the image in question, +#' it will not be able to `docker pull` the image again, +#' because the `GITHUB_TOKEN` will have expired by then. #' Only a new workflow run can heal the app in this scenario. #' It remains to be seen how common this problem is. #' @@ -39,8 +67,12 @@ az_webapp_config_muggle <- function(name = Sys.getenv("MUGGLE_PKG_NAME"), plan, resource_group, subscription, - docker_registry_server_user = Sys.getenv("GITHUB_ACTOR"), - docker_registry_server_password = Sys.getenv("GITHUB_TOKEN"), + docker_registry_server_user = Sys.getenv( + "GITHUB_ACTOR" + ), + docker_registry_server_password = Sys.getenv( + "GITHUB_TOKEN" + ), restart = FALSE) { shinycaas::az_webapp_config( name = name, diff --git a/R/github.R b/R/github.R index 3664c3a..5037aef 100644 --- a/R/github.R +++ b/R/github.R @@ -1,10 +1,16 @@ #' Get the full docker image url for an image on GitHub Packages #' #' Helpful to quickly run an image locally or deploy it. -#' See the [GitHub Packages for Docker documentation](https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages) for details. -#' Forms a URL of the form `docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION` -#' Notice how, different from Docker Hub, docker images on GitHub Packages have an `IMAGE_NAME` appended to the familiar `OWNER/REPOSITORY` pattern. -#' These `IMAGE_NAME`s are immutable (cannot be changed nor deleted) and must be unique per GitHub repository. +#' See the +#' [GitHub Packages for Docker documentation](https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages) +#' for details. +#' Forms a URL of the form +#' `docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION` +#' Notice how, different from Docker Hub, +#' docker images on GitHub Packages have an `IMAGE_NAME` +#' appended to the familiar `OWNER/REPOSITORY` pattern. +#' These `IMAGE_NAME`s are immutable (cannot be changed nor deleted) +#' and must be unique per GitHub repository. #' #' @param image_name,version Image name and version as strings. #' Defaults to muggle convention. @@ -17,7 +23,9 @@ #' @family compute environment functions #' #' @export -gh_pkgs_image_url <- function(image_name = gh_pkgs_image_name(target = "runtime"), +gh_pkgs_image_url <- function(image_name = gh_pkgs_image_name( + target = "runtime" + ), version = gh_pkgs_image_version(), repo_spec = gh_repo_spec()) { paste( @@ -32,8 +40,12 @@ gh_pkgs_image_url <- function(image_name = gh_pkgs_image_name(target = "runtime" #' Get the docker image name conventionally used in muggle projects #' #' @param target Build target for multistage muggle builds. -#' By convention, for a package `foo`, {muggle} would build a `foo-buildtime` and `foo-runtime` for the `buildtime` and `runtime` docker multistage build targets, respectively. -#' A `buildtime` target will exist for all {muggle} projects, a `runtime` target only for projects with deployed runtimes such as a shiny app +#' By convention, for a package `foo`, {muggle} would build a `foo-buildtime` +#' and `foo-runtime` for the `buildtime` and `runtime` docker multistage +#' build targets, respectively. +#' A `buildtime` target will exist for all {muggle} projects, +#' a `runtime` target only for projects +#' with deployed runtimes such as a shiny app #' #' @export gh_pkgs_image_name <- function(target = c("buildtime", "runtime")) { @@ -42,7 +54,9 @@ gh_pkgs_image_name <- function(target = c("buildtime", "runtime")) { } #' @describeIn gh_pkgs_image_url -#' Get the sha of the *latest* `git commit` if on GitHub Actions, or the *head* reference (the branch or tag) otherwise (not recommended for reproducibility). +#' Get the sha of the *latest* `git commit` if on GitHub Actions, +#' or the *head* reference (the branch or tag) otherwise +#' (not recommended for reproducibility). gh_pkgs_image_version <- function() { if (is_github_actions()) { return(Sys.getenv("GITHUB_SHA")) @@ -71,7 +85,8 @@ gh_repo_spec <- function() { #' Determine if code is running inside GitHub Actions #' -#' Looks for the `GITHUB_ACTIONS` environment variable, as [documented](https://docs.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables) +#' Looks for the `GITHUB_ACTIONS` environment variable, as +#' [documented](https://docs.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables) #' #' @noRd is_github_actions <- function() { diff --git a/R/helpers.R b/R/helpers.R index f8c49a0..6108826 100644 --- a/R/helpers.R +++ b/R/helpers.R @@ -1,7 +1,8 @@ #' Browse to URL #' #' @details -#' This function is copied from an unexported function in [usethis](https://github.com/r-lib/usethis/blob/23dd62c5e7713ed8ecceae82e6338f795d30ba92/R/helpers.R). +#' This function is copied from an unexported function in +#' [usethis](https://github.com/r-lib/usethis/blob/23dd62c5e7713ed8ecceae82e6338f795d30ba92/R/helpers.R). #' #' @param ... Elements of the URL #' @param open `[logical(1)]` giving whether the URL should be opened @@ -74,8 +75,8 @@ local_muggle_file <- function(muggle_file, .local_envir = parent.frame()) { #' Determine if code is running inside GitHub Actions #' -#' Looks for the `GITHUB_ACTIONS` environment variable, -#' as [documented](https://docs.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables) +#' Looks for the `GITHUB_ACTIONS` environment variable, as +#' [documented](https://docs.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables) #' #' @keywords internal is_github_actions <- function() { diff --git a/R/pkgdown.R b/R/pkgdown.R index 376dc63..383d8eb 100644 --- a/R/pkgdown.R +++ b/R/pkgdown.R @@ -1,15 +1,21 @@ #' Replacement versions of [pkgdown::build_site()] etc. with muggle defaults #' -#' Sets some muggle defaults for pkgdown to minimize code duplication across muggle projects. +#' Sets some muggle defaults for pkgdown to minimize code duplication across +#' muggle projects. #' This includes overrides of `_pkgdown.yml` and `_site.yml`. #' #' @section Additions to pkgdown: -#' These replacement versions of pkgdown functions make the following changes to pkgdown, as applicable: -#' - If there are `vignettes/`, declaring a default vignette rendering function ([local_siteyaml()]) -#' - Overriding some values in `_pkgdown.yml` by appending [override_pkgdownyaml()]) to `override`. +#' These replacement versions of pkgdown functions make the following changes +#' to pkgdown, as applicable: +#' - If there are `vignettes/`, +#' declaring a default vignette rendering function ([local_siteyaml()]) +#' - Overriding some values in `_pkgdown.yml` +#' by appending [override_pkgdownyaml()]) to `override`. #' Be careful not to provide conflicting overrides. -#' - Sets `run_dont_run = TRUE`, so that examples inside `\dontrun{}` are still run inside of pkgdown. -#' Examples often need to be skipped on CRAN and other checks, though not when building pkgdown. +#' - Sets `run_dont_run = TRUE`, so that examples inside `\dontrun{}` +#' are still run inside of pkgdown. +#' Examples often need to be skipped on CRAN and other checks, +#' though not when building pkgdown. #' #' @inheritSection pkgdown::build_site YAML config - navbar #' @inheritParams pkgdown::build_site @@ -61,24 +67,33 @@ override_pkgdownyaml <- function() { #' Wraps [local_muggle_file()] to delete file upon use. #' #' @details -#' This `vignettes/_site.yml` declares the default vignette rendering function for muggle vignettes. -#' To enable it, you also must declare in the yaml frontmatter *for each of the vignettes*: +#' This `vignettes/_site.yml` declares the default vignette rendering function +#' for muggle vignettes. +#' To enable it, +#' you also must declare in the yaml frontmatter *for each of the vignettes*: #' #' ```yaml #' pkgdown: #' as_is: true #' ``` #' -#' For an example of such a vignette with all its features, see `vignette("vignette-muggle")` +#' For an example of such a vignette with all its features, +#' see `vignette("vignette-muggle")` #' #' @section Features: #' ## Backported Bookdown Features -#' By default, pkgdown builds vignettes (or rather, articles) using a special format based on [rmarkdown::html_document()]. -#' This format does not include the automatic numbering and crossreferencing of figures, tables, equations, and (for cross-references) sections supported by [bookdown](http://bookdown.org). -#' The [`bookdown::html_document2()`](https://bookdown.org/yihui/bookdown/a-single-document.html) render function backports these features for uses outside of bookdown. +#' By default, pkgdown builds vignettes (or rather, articles) +#' using a special format based on [rmarkdown::html_document()]. +#' This format does not include the automatic numbering and +#' crossreferencing of figures, tables, equations, and (for cross-references) +#' sections supported by [bookdown](http://bookdown.org). +#' The +#' [`bookdown::html_document2()`](https://bookdown.org/yihui/bookdown/a-single-document.html) +#' render function backports these features for uses outside of bookdown. #' #' ## Raw HTML -#' Pandoc extensions are set to allow correctly indented raw HTML inside vignettes. +#' Pandoc extensions are set to allow correctly indented raw HTML +#' inside vignettes. #' #' @inheritParams local_muggle_file #' @family pkgdown functions @@ -90,7 +105,8 @@ local_siteyaml <- function(.local_envir = parent.frame()) { #' Retrieve the public URL from the `DESCRIPTION` #' #' Chooses whichever URL in the `DESCRIPTION` is *not* on github.com. -#' That's assumed to be the public-facing website, such as a pkgdown website on GitHub pages. +#' That's assumed to be the public-facing website, +#' such as a pkgdown website on GitHub pages. #' #' @keywords internal get_url_from_desc <- function() { diff --git a/R/setup.R b/R/setup.R index 492ee7e..316b641 100644 --- a/R/setup.R +++ b/R/setup.R @@ -2,22 +2,37 @@ #' #' @description #' Set up, or migrate to a muggle project. -#' Wraps the following steps, *if the respective files or configuration do not already exist*: +#' Wraps the following steps, *if the respective files +#' or configuration do not already exist*: #' -#' 1. **Package Structure**: Sets up scaffolding via [usethis::create_package()] and asks the user to complete the `DESCRIPTION`. -#' 1. **Editors/IDEs**: Sets up [vscode](http://code.visualstudio.com) and RStudio as editors. -#' 1. **Git/GitHub**: Initialises a git repo via [usethis::use_git()], creates a repo on GitHub and sets it as an origin remote. -#' 1. **README**: Adds a `README.md` via [usethis::use_readme_md()] and asks the user to complete it. -#' 1. **Testing**: Sets up the project for unit tests via [usethis::use_testthat()] and test coverage via [usethis::use_coverage()]. -#' 1. **Documentation**: Sets up markdown support in roxygen via [usethis::use_roxygen_md()], package documentation via [usethis::use_package_doc()] and ddds a pkgdown website via [usethis::use_pkgdown()]. +#' 1. **Package Structure**: +#' Sets up scaffolding via [usethis::create_package()] +#' and asks the user to complete the `DESCRIPTION`. +#' 1. **Editors/IDEs**: +#' Sets up [vscode](http://code.visualstudio.com) +#' and RStudio as editors. +#' 1. **Git/GitHub**: +#' Initialises a git repo via [usethis::use_git()], +#' creates a repo on GitHub and sets it as an origin remote. +#' 1. **README**: +#' Adds a `README.md` via [usethis::use_readme_md()] +#' and asks the user to complete it. +#' 1. **Quality Control**: +#' Sets up the project for unit tests via [usethis::use_testthat()] +#' and test coverage via [usethis::use_coverage()]. +#' 1. **Documentation**: +#' Sets up markdown support in roxygen via [usethis::use_roxygen_md()], +#' package documentation via [usethis::use_package_doc()] +#' and adds a pkgdown website via [usethis::use_pkgdown()]. #' 1. **Workflow Automation**: sets up caching at [lib_cache_path] and tba. #' 1. **Compute Environment**: tba. #' #' #' @details # Warning #' - Must not be run *inside* a package, but at the root of all packages -#' - If run on an existing project, the project should be under version control, with a clean working tree. -#' The user should check all changes. +#' - If run on an existing project, +#' the project should be under version control, with a clean working tree. +#' The user should check all changes. #' #' @inheritParams usethis::create_package #' @param license one of the license functions in [usethis] @@ -64,7 +79,7 @@ create_muggle_package <- function(path, usethis::use_git() # imperfect check for whether github remote is set if (nrow(gert::git_remote_list()) == 0) { - # if there was already a git remote as will be the case for existing projects, + # if there was already a git remote as will be true for existing projects, # the whole function would error out here usethis::use_github( organisation = organisation, diff --git a/README.md b/README.md index 97a922e..4a6a2c9 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,6 @@ [![muggle-buildtime Docker Pulls](https://img.shields.io/docker/pulls/subugoe/muggle-buildtime-onbuild?label=muggle-buildtime%20docker%20pulls&style=flat)](https://hub.docker.com/repository/docker/subugoe/muggle-buildtime-onbuild) [![muggle-runtime Docker Pulls](https://img.shields.io/docker/pulls/subugoe/muggle-runtime-onbuild?label=muggle-runtime%20docker%20pulls&style=flat)](https://hub.docker.com/repository/docker/subugoe/muggle-runtime-onbuild) - - ## Overview > Reproducible DevOps Strictly Without Magic diff --git a/man/az_webapp_config_muggle.Rd b/man/az_webapp_config_muggle.Rd index 15ce6c0..e45a703 100644 --- a/man/az_webapp_config_muggle.Rd +++ b/man/az_webapp_config_muggle.Rd @@ -42,27 +42,55 @@ Wraps the \href{https://docs.microsoft.com/en-us/cli/azure/?view=azure-cli-lates Wrapping with muggle defaults; use only inside muggle projects. } \section{Authenticating Against GitHub Packages}{ -Because muggle stores the docker images with the shiny runtimes on GitHub Packages, Azure must pull images from there, not the commonly used Docker Hub. +Because muggle stores the docker images with the shiny runtimes on +GitHub Packages, Azure must pull images from there, +not the commonly used Docker Hub. -Currently, GitHub Packages does not offer public images, even for public repositories (\href{https://github.com/subugoe/muggle/issues/133}{#133}). -That means that Azure must be \href{https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages}{authenticated} to be able to download the runtime images. -This is the inverse of the the \verb{azure login} GitHub Action, which authenticates the GitHub Actions runtime to talk to Azure. +Currently, GitHub Packages does not offer public images, +even for public repositories +(\href{https://github.com/subugoe/muggle/issues/133}{#133}) +That means that Azure must be +\href{https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages}{authenticated} +to be able to download the runtime images. +This is the inverse of the the \verb{azure login} GitHub Action, +which authenticates the GitHub Actions runtime to talk to Azure. -There are (only) two ways to do this, both suboptimal (\href{https://github.com/subugoe/muggle/issues/132}{#132}): +There are (only) two ways to do this, +both suboptimal (\href{https://github.com/subugoe/muggle/issues/132}{#132}): \enumerate{ -\item You can authenticate Azure with a \href{https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token}{personal access token (PAT)} and the corresponding \strong{static GitHub username}. -No matter who commits and triggered the deployment, always the same personal GitHub credentials (say, those of Jane Doe) will be used. -To do this, the volunteering team member should create a PAT on GitHub, scope it minimally to only read packages, and paste that into the Azure web ui at portal.azure.com. -A minimally scoped PAT may be reasonably safe, but the approach is still cumbersome and awkward. -\item You can authenticate Azure towards GitHub Packages \strong{with the \code{GITHUB_ACTOR} and \code{GITHUB_TOKEN} pair} \href{https://docs.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token}{furnished} for GitHub Actions, from which the deployment takes place. -The \code{GITHUB_ACTOR} environment variable will always be the GitHub username of whoever triggered the workflow run, and therefore, the deployment. -The \code{GITHUB_TOKEN} is a PAT scoped to \emph{only} that repo and will expire automatically after the workflow run is completed. -To use this authentication, use the below defaults and expose the \code{GITHUB_TOKEN} to in your workflow \verb{*.yaml} file.\if{html}{\out{
}}\preformatted{env: +\item You can authenticate Azure with a +\href{https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token}{personal access token (PAT)} +and the corresponding \strong{static GitHub username}. +No matter who commits and triggered the deployment, +always the same personal GitHub credentials +(say, those of Jane Doe) will be used. +To do this, the volunteering team member should create a PAT on GitHub, +scope it minimally to only read packages, +and paste that into the Azure web ui at portal.azure.com. +A minimally scoped PAT may be reasonably safe, +but the approach is still cumbersome and awkward. +\item You can authenticate Azure towards GitHub Packages +\strong{with the \code{GITHUB_ACTOR} and \code{GITHUB_TOKEN} pair} +\href{https://docs.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token}{furnished} +for GitHub Actions, from which the deployment takes place. +The \code{GITHUB_ACTOR} environment variable will always be +the GitHub username of whoever triggered the workflow run, +and therefore, the deployment. +The \code{GITHUB_TOKEN} is a PAT scoped to \emph{only} that repo and will expire +automatically after the workflow run is completed. +To use this authentication, use the below defaults and expose the +\code{GITHUB_TOKEN} to in your workflow \verb{*.yaml} file.\if{html}{\out{
}}\preformatted{env: GITHUB_TOKEN: $\{\{ secrets.GITHUB_TOKEN \}\} }\if{html}{\out{
}} -This is a more elegant, and arguably more secure solution, though the \code{GITHUB_TOKEN} still has more scope than just to read packages, if only for the repo in question. -This form of authentication seems to work reliably, but may break future app (re)starts on Azure: Should Azure loose the docker cache of the image in question, it will not be able to \verb{docker pull} the image again, because the \code{GITHUB_TOKEN} will have expired by then. +This is a more elegant, and arguably more secure solution, +though the \code{GITHUB_TOKEN} still has more scope than just to read packages, +if only for the repo in question. +This form of authentication seems to work reliably, +but may break future app (re)starts on Azure: +Should Azure loose the docker cache of the image in question, +it will not be able to \verb{docker pull} the image again, +because the \code{GITHUB_TOKEN} will have expired by then. Only a new workflow run can heal the app in this scenario. It remains to be seen how common this problem is. } diff --git a/man/build_site2.Rd b/man/build_site2.Rd index 09ee006..1e76fda 100644 --- a/man/build_site2.Rd +++ b/man/build_site2.Rd @@ -53,7 +53,8 @@ pandoc. This is useful when debugging.} }} } \description{ -Sets some muggle defaults for pkgdown to minimize code duplication across muggle projects. +Sets some muggle defaults for pkgdown to minimize code duplication across +muggle projects. This includes overrides of \verb{_pkgdown.yml} and \verb{_site.yml}. } \section{Related Functions and Methods}{ @@ -67,13 +68,18 @@ This includes overrides of \verb{_pkgdown.yml} and \verb{_site.yml}. \section{Additions to pkgdown}{ -These replacement versions of pkgdown functions make the following changes to pkgdown, as applicable: +These replacement versions of pkgdown functions make the following changes +to pkgdown, as applicable: \itemize{ -\item If there are \verb{vignettes/}, declaring a default vignette rendering function (\code{\link[=local_siteyaml]{local_siteyaml()}}) -\item Overriding some values in \verb{_pkgdown.yml} by appending \code{\link[=override_pkgdownyaml]{override_pkgdownyaml()}}) to \code{override}. +\item If there are \verb{vignettes/}, +declaring a default vignette rendering function (\code{\link[=local_siteyaml]{local_siteyaml()}}) +\item Overriding some values in \verb{_pkgdown.yml} +by appending \code{\link[=override_pkgdownyaml]{override_pkgdownyaml()}}) to \code{override}. Be careful not to provide conflicting overrides. -\item Sets \code{run_dont_run = TRUE}, so that examples inside \verb{\dontrun{}} are still run inside of pkgdown. -Examples often need to be skipped on CRAN and other checks, though not when building pkgdown. +\item Sets \code{run_dont_run = TRUE}, so that examples inside \verb{\dontrun{}} +are still run inside of pkgdown. +Examples often need to be skipped on CRAN and other checks, +though not when building pkgdown. } } diff --git a/man/create_muggle_package.Rd b/man/create_muggle_package.Rd index b780638..9a5de1b 100644 --- a/man/create_muggle_package.Rd +++ b/man/create_muggle_package.Rd @@ -35,14 +35,28 @@ such that you have permission to create repositories in this } \description{ Set up, or migrate to a muggle project. -Wraps the following steps, \emph{if the respective files or configuration do not already exist}: +Wraps the following steps, \emph{if the respective files +or configuration do not already exist}: \enumerate{ -\item \strong{Package Structure}: Sets up scaffolding via \code{\link[usethis:create_package]{usethis::create_package()}} and asks the user to complete the \code{DESCRIPTION}. -\item \strong{Editors/IDEs}: Sets up \href{http://code.visualstudio.com}{vscode} and RStudio as editors. -\item \strong{Git/GitHub}: Initialises a git repo via \code{\link[usethis:use_git]{usethis::use_git()}}, creates a repo on GitHub and sets it as an origin remote. -\item \strong{README}: Adds a \code{README.md} via \code{\link[usethis:use_readme_rmd]{usethis::use_readme_md()}} and asks the user to complete it. -\item \strong{Testing}: Sets up the project for unit tests via \code{\link[usethis:use_testthat]{usethis::use_testthat()}} and test coverage via \code{\link[usethis:use_coverage]{usethis::use_coverage()}}. -\item \strong{Documentation}: Sets up markdown support in roxygen via \code{\link[usethis:use_roxygen_md]{usethis::use_roxygen_md()}}, package documentation via \code{\link[usethis:use_package_doc]{usethis::use_package_doc()}} and ddds a pkgdown website via \code{\link[usethis:use_pkgdown]{usethis::use_pkgdown()}}. +\item \strong{Package Structure}: +Sets up scaffolding via \code{\link[usethis:create_package]{usethis::create_package()}} +and asks the user to complete the \code{DESCRIPTION}. +\item \strong{Editors/IDEs}: +Sets up \href{http://code.visualstudio.com}{vscode} +and RStudio as editors. +\item \strong{Git/GitHub}: +Initialises a git repo via \code{\link[usethis:use_git]{usethis::use_git()}}, +creates a repo on GitHub and sets it as an origin remote. +\item \strong{README}: +Adds a \code{README.md} via \code{\link[usethis:use_readme_rmd]{usethis::use_readme_md()}} +and asks the user to complete it. +\item \strong{Quality Control}: +Sets up the project for unit tests via \code{\link[usethis:use_testthat]{usethis::use_testthat()}} +and test coverage via \code{\link[usethis:use_coverage]{usethis::use_coverage()}}. +\item \strong{Documentation}: +Sets up markdown support in roxygen via \code{\link[usethis:use_roxygen_md]{usethis::use_roxygen_md()}}, +package documentation via \code{\link[usethis:use_package_doc]{usethis::use_package_doc()}} +and adds a pkgdown website via \code{\link[usethis:use_pkgdown]{usethis::use_pkgdown()}}. \item \strong{Workflow Automation}: sets up caching at \link{lib_cache_path} and tba. \item \strong{Compute Environment}: tba. } @@ -50,7 +64,8 @@ Wraps the following steps, \emph{if the respective files or configuration do not \section{Warning}{ \itemize{ \item Must not be run \emph{inside} a package, but at the root of all packages -\item If run on an existing project, the project should be under version control, with a clean working tree. +\item If run on an existing project, +the project should be under version control, with a clean working tree. The user should check all changes. } } diff --git a/man/get_url_from_desc.Rd b/man/get_url_from_desc.Rd index 5f34250..e476761 100644 --- a/man/get_url_from_desc.Rd +++ b/man/get_url_from_desc.Rd @@ -8,6 +8,7 @@ get_url_from_desc() } \description{ Chooses whichever URL in the \code{DESCRIPTION} is \emph{not} on github.com. -That's assumed to be the public-facing website, such as a pkgdown website on GitHub pages. +That's assumed to be the public-facing website, +such as a pkgdown website on GitHub pages. } \keyword{internal} diff --git a/man/gh_pkgs_image_url.Rd b/man/gh_pkgs_image_url.Rd index c7375d0..af5b917 100644 --- a/man/gh_pkgs_image_url.Rd +++ b/man/gh_pkgs_image_url.Rd @@ -24,18 +24,28 @@ Defaults to muggle convention.} Users should stick to the default; manual entry is only used for testing.} \item{target}{Build target for multistage muggle builds. -By convention, for a package \code{foo}, {muggle} would build a \code{foo-buildtime} and \code{foo-runtime} for the \code{buildtime} and \code{runtime} docker multistage build targets, respectively. -A \code{buildtime} target will exist for all {muggle} projects, a \code{runtime} target only for projects with deployed runtimes such as a shiny app} +By convention, for a package \code{foo}, {muggle} would build a \code{foo-buildtime} +and \code{foo-runtime} for the \code{buildtime} and \code{runtime} docker multistage +build targets, respectively. +A \code{buildtime} target will exist for all {muggle} projects, +a \code{runtime} target only for projects +with deployed runtimes such as a shiny app} } \value{ character string } \description{ Helpful to quickly run an image locally or deploy it. -See the \href{https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages}{GitHub Packages for Docker documentation} for details. -Forms a URL of the form \code{docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION} -Notice how, different from Docker Hub, docker images on GitHub Packages have an \code{IMAGE_NAME} appended to the familiar \code{OWNER/REPOSITORY} pattern. -These \code{IMAGE_NAME}s are immutable (cannot be changed nor deleted) and must be unique per GitHub repository. +See the +\href{https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages}{GitHub Packages for Docker documentation} +for details. +Forms a URL of the form +\code{docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION} +Notice how, different from Docker Hub, +docker images on GitHub Packages have an \code{IMAGE_NAME} +appended to the familiar \code{OWNER/REPOSITORY} pattern. +These \code{IMAGE_NAME}s are immutable (cannot be changed nor deleted) +and must be unique per GitHub repository. } \section{Related Functions and Methods}{ \subsection{Functions}{ @@ -43,7 +53,9 @@ These \code{IMAGE_NAME}s are immutable (cannot be changed nor deleted) and must \item \code{gh_pkgs_image_name}: Get the docker image name conventionally used in muggle projects } \itemize{ -\item \code{gh_pkgs_image_version}: Get the sha of the \emph{latest} \verb{git commit} if on GitHub Actions, or the \emph{head} reference (the branch or tag) otherwise (not recommended for reproducibility). +\item \code{gh_pkgs_image_version}: Get the sha of the \emph{latest} \verb{git commit} if on GitHub Actions, +or the \emph{head} reference (the branch or tag) otherwise +(not recommended for reproducibility). }}} \seealso{ diff --git a/man/install_sysdeps.Rd b/man/install_sysdeps.Rd index 3eb1278..9dd8076 100644 --- a/man/install_sysdeps.Rd +++ b/man/install_sysdeps.Rd @@ -7,7 +7,8 @@ install_sysdeps() } \description{ -Infers and installs system dependencies from \code{DESCRIPTION} via the \href{https://github.com/r-hub/sysreqs}{r-hub/sysreqs} project. +Infers and installs system dependencies from \code{DESCRIPTION} +via the \href{https://github.com/r-hub/sysreqs}{r-hub/sysreqs} project. } \seealso{ Other compute environment functions: diff --git a/man/is_github_actions.Rd b/man/is_github_actions.Rd index 63f217f..b15e2a4 100644 --- a/man/is_github_actions.Rd +++ b/man/is_github_actions.Rd @@ -7,7 +7,7 @@ is_github_actions() } \description{ -Looks for the \code{GITHUB_ACTIONS} environment variable, -as \href{https://docs.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables}{documented} +Looks for the \code{GITHUB_ACTIONS} environment variable, as +\href{https://docs.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables}{documented} } \keyword{internal} diff --git a/man/lib_cache_path.Rd b/man/lib_cache_path.Rd index 995627b..1d9b198 100644 --- a/man/lib_cache_path.Rd +++ b/man/lib_cache_path.Rd @@ -11,7 +11,8 @@ An object of class \code{fs_path} (inherits from \code{character}) of length 1. lib_cache_path } \description{ -This directory serves to copy the package cache into the docker build context on GitHub actions. +This directory serves to copy the package cache +into the docker build context on GitHub actions. } \seealso{ Other compute environment functions: diff --git a/man/local_siteyaml.Rd b/man/local_siteyaml.Rd index ecdb25b..080ed09 100644 --- a/man/local_siteyaml.Rd +++ b/man/local_siteyaml.Rd @@ -14,25 +14,34 @@ Upgrades vignettes to muggle default. Wraps \code{\link[=local_muggle_file]{local_muggle_file()}} to delete file upon use. } \details{ -This \verb{vignettes/_site.yml} declares the default vignette rendering function for muggle vignettes. -To enable it, you also must declare in the yaml frontmatter \emph{for each of the vignettes}:\if{html}{\out{
}}\preformatted{pkgdown: +This \verb{vignettes/_site.yml} declares the default vignette rendering function +for muggle vignettes. +To enable it, +you also must declare in the yaml frontmatter \emph{for each of the vignettes}:\if{html}{\out{
}}\preformatted{pkgdown: as_is: true }\if{html}{\out{
}} -For an example of such a vignette with all its features, see \code{vignette("vignette-muggle")} +For an example of such a vignette with all its features, +see \code{vignette("vignette-muggle")} } \section{Features}{ \subsection{Backported Bookdown Features}{ -By default, pkgdown builds vignettes (or rather, articles) using a special format based on \code{\link[rmarkdown:html_document]{rmarkdown::html_document()}}. -This format does not include the automatic numbering and crossreferencing of figures, tables, equations, and (for cross-references) sections supported by \href{http://bookdown.org}{bookdown}. -The \href{https://bookdown.org/yihui/bookdown/a-single-document.html}{\code{bookdown::html_document2()}} render function backports these features for uses outside of bookdown. +By default, pkgdown builds vignettes (or rather, articles) +using a special format based on \code{\link[rmarkdown:html_document]{rmarkdown::html_document()}}. +This format does not include the automatic numbering and +crossreferencing of figures, tables, equations, and (for cross-references) +sections supported by \href{http://bookdown.org}{bookdown}. +The +\href{https://bookdown.org/yihui/bookdown/a-single-document.html}{\code{bookdown::html_document2()}} +render function backports these features for uses outside of bookdown. } \subsection{Raw HTML}{ -Pandoc extensions are set to allow correctly indented raw HTML inside vignettes. +Pandoc extensions are set to allow correctly indented raw HTML +inside vignettes. } } diff --git a/man/use_onbuild_image.Rd b/man/use_onbuild_image.Rd index d8dddf1..e69205a 100644 --- a/man/use_onbuild_image.Rd +++ b/man/use_onbuild_image.Rd @@ -7,7 +7,8 @@ use_onbuild_image() } \description{ -Adds or updates a \code{Dockerfile} and corresponding \code{main.yaml} GitHub Actions workflow. +Adds or updates a \code{Dockerfile} +and corresponding \code{main.yaml} GitHub Actions workflow. } \seealso{ Other compute environment functions: diff --git a/man/view_url.Rd b/man/view_url.Rd index eaaa245..beb1fbd 100644 --- a/man/view_url.Rd +++ b/man/view_url.Rd @@ -15,6 +15,7 @@ view_url(..., open = interactive()) Browse to URL } \details{ -This function is copied from an unexported function in \href{https://github.com/r-lib/usethis/blob/23dd62c5e7713ed8ecceae82e6338f795d30ba92/R/helpers.R}{usethis}. +This function is copied from an unexported function in +\href{https://github.com/r-lib/usethis/blob/23dd62c5e7713ed8ecceae82e6338f795d30ba92/R/helpers.R}{usethis}. } \keyword{internal} From b5f0fe9e3f36caa30e5308254154ce987657f9ae Mon Sep 17 00:00:00 2001 From: Maximilian Held Date: Thu, 18 Feb 2021 20:32:47 +0100 Subject: [PATCH 4/4] remove trailing whitespace --- tests/testthat/test-pkgdown.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/testthat/test-pkgdown.R b/tests/testthat/test-pkgdown.R index fc4e30a..79dcf94 100644 --- a/tests/testthat/test-pkgdown.R +++ b/tests/testthat/test-pkgdown.R @@ -1,7 +1,7 @@ test_that("public url is correctly inferred", { local_create_package() desc::desc_set_urls(c( - "https://subugoe.github.io/muggle", + "https://subugoe.github.io/muggle", "https://github.com/subugoe/muggle", "https://www.google.com" ))