feat: new gh action to document package - fix #51

.github/workflows/document-package.yaml

@@ -0,0 +1,42 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    paths: ["R/**"]
+
+name: Document
+
+jobs:
+  document:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Setup R
+        uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - name: Install dependencies
+        uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::roxygen2
+          needs: roxygen2
+
+      - name: Document
+        run: roxygen2::roxygenise()
+        shell: Rscript {0}
+
+      - name: Commit and push changes
+        run: |
+          git config --local user.name "$GITHUB_ACTOR"
+          git config --local user.email "$GITHUB_ACTOR@users.noreply.github.com"
+          git add man/\* NAMESPACE DESCRIPTION
+          git commit -m "doc: update documentation" || echo "No changes to commit"
+          git pull --ff-only
+          git push origin

NAMESPACE

@@ -15,6 +15,7 @@ export(add_github_actions_check_badge)
 export(add_github_actions_citation)
 export(add_github_actions_codecov)
 export(add_github_actions_codecov_badge)
+export(add_github_actions_document)
 export(add_github_actions_pkgdown)
 export(add_github_actions_pkgdown_badge)
 export(add_github_actions_render)

NEWS.md

@@ -7,6 +7,8 @@
   * `add_code_of_conduct()` adds a `CODE_OF_CONDUCT.md` file
   * `add_github_actions_citation()` adds a new GitHub action to update the 
   `CITATION.cff` file
+  * `add_github_actions_document()` adds a new GitHub action to update `Rd` files,
+  the `NAMESPACE` and the `DESCRIPTION` files
 
 * **Improvements**
 

R/add_github_actions_document.R

@@ -0,0 +1,83 @@
+#' Setup GitHub Actions to document package
+#' 
+#' @description 
+#' This function creates a configuration file (`.yaml`) to setup GitHub Actions 
+#' to document the package and update the `Rd` files in the `man/`, the 
+#' `NAMESPACE` and `DESCRIPTION` files.
+#' This workflow is derived 
+#' from \url{https://github.com/r-lib/actions/tree/v2-branch/examples}.
+#' This file will be written as `.github/workflows/document-package.yaml`.
+#' 
+#' @param open A logical value. If `TRUE` (default) the file is opened in the 
+#'   editor.
+#' 
+#' @param overwrite A logical value. If this file is already present and 
+#'   `overwrite = TRUE`, it will be erased and replaced. Default is `FALSE`.
+#'   
+#' @param quiet A logical value. If `TRUE` messages are deleted. Default is 
+#'   `FALSE`.
+#' 
+#' @return No return value.
+#'
+#' @export
+#' 
+#' @family development functions
+#'
+#' @examples
+#' \dontrun{
+#' add_github_actions_document()
+#' }
+
+add_github_actions_document <- function(open = FALSE, overwrite = FALSE,
+                                        quiet = FALSE) {
+
+
+  stop_if_not_logical(open, overwrite, quiet)
+
+  if (!dir.exists(file.path(path_proj(), ".git"))) {
+    stop("The project is not versioning with git.")
+  }
+
+
+  path <- file.path(path_proj(), ".github", "workflows", 
+                    "document-package.yaml")
+
+
+  ## Do not replace current file but open it if required ----
+
+  if (file.exists(path) && !overwrite) {
+
+    if (!open) {
+
+      stop("An '.github/workflows/document-package.yaml' file is already ",
+           "present. If you want to replace it, please use `overwrite = TRUE`.")
+
+    } else {
+
+      edit_file(path)
+      return(invisible(NULL))
+    }
+  }
+
+
+  ## Copy Template ----
+
+  dir.create(file.path(path_proj(), ".github", "workflows"), 
+             showWarnings = FALSE, recursive = TRUE)
+
+  invisible(
+    file.copy(system.file(file.path("templates", "document-package.yaml"), 
+                          package = "rcompendium"), path))
+
+
+  if (!quiet) {
+    ui_done(paste0("Writing ", 
+                   "{ui_value('.github/workflows/document-package.yaml')} ", 
+                   "file"))
+  }
+
+
+  if (open) edit_file(path)
+
+  invisible(NULL)
+}

_pkgdown.yml

@@ -80,6 +80,7 @@ reference:
   - add_github_actions_codecov
   - add_github_actions_render
   - add_github_actions_citation
+  - add_github_actions_document
 
 - title: Utilities functions
   desc: |

inst/templates/document-package.yaml

@@ -0,0 +1,42 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    paths: ["R/**"]
+
+name: Document
+
+jobs:
+  document:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Setup R
+        uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - name: Install dependencies
+        uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::roxygen2
+          needs: roxygen2
+
+      - name: Document
+        run: roxygen2::roxygenise()
+        shell: Rscript {0}
+
+      - name: Commit and push changes
+        run: |
+          git config --local user.name "$GITHUB_ACTOR"
+          git config --local user.email "$GITHUB_ACTOR@users.noreply.github.com"
+          git add man/\* NAMESPACE DESCRIPTION
+          git commit -m "doc: update documentation" || echo "No changes to commit"
+          git pull --ff-only
+          git push origin