Merge pull request #19 from ImperialCollegeLondon/rtools

Add: toolchain to build packages, preview website locally, and a bonus section

.github/workflows/lint.yaml

@@ -0,0 +1,34 @@
+# 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:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+name: lint.yaml
+
+permissions: read-all
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::lintr, local::.
+          needs: lint
+
+      - name: Lint
+        run: lintr::lint_package()
+        shell: Rscript {0}
+        env:
+          LINTR_ERROR_ON_LINT: true

.github/workflows/render-rmarkdown.yaml

@@ -0,0 +1,37 @@
+# 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: ['**.Rmd']
+
+name: render-rmarkdown.yaml
+
+permissions: read-all
+
+jobs:
+  render-rmarkdown:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
+      - uses: r-lib/actions/setup-r@v2
+
+      - uses: r-lib/actions/setup-renv@v2
+
+      - name: Render Rmarkdown files and Commit Results
+        run: |
+          RMD_PATH=($(git diff --name-only ${{ github.event.before }} ${{ github.sha }} | grep '[.]Rmd$'))
+          Rscript -e 'for (f in commandArgs(TRUE)) if (file.exists(f)) rmarkdown::render(f)' ${RMD_PATH[*]}
+          git config --local user.name "$GITHUB_ACTOR"
+          git config --local user.email "[email protected]"
+          git commit ${RMD_PATH[*]/.Rmd/.md} -m 'Re-build Rmarkdown files' || echo "No changes to commit"
+          git push origin || echo "No changes to commit"

DESCRIPTION

@@ -16,3 +16,5 @@ Suggests:
     testthat (>= 3.0.0)
 Config/testthat/edition: 3
 RoxygenNote: 7.3.2
+Imports: 
+    rmarkdown

R/add.R

@@ -8,6 +8,6 @@
 #'
 #' @examples add(5, 4)
 add <- function(x, y) {
-  z = x + y
+  z <- x + y
   return(z)
 }

README.Rmd

@@ -4,18 +4,10 @@ output: github_document
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
-```{r, include = FALSE}
-knitr::opts_chunk$set(
-  collapse = TRUE,
-  comment = "#>",
-  fig.path = "man/figures/README-",
-  out.width = "100%"
-)
-```
-
 # repositoryr
 
 <!-- badges: start -->
+[![R-CMD-check](https://github.com/ImperialCollegeLondon/repositoryr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ImperialCollegeLondon/repositoryr/actions/workflows/R-CMD-check.yaml)
 <!-- badges: end -->
 
 The goal of repositoryr is to provide a step by step guide to creating a R package repository.
@@ -28,6 +20,14 @@ The goal of repositoryr is to provide a step by step guide to creating a R packa
   - Use [Posit Cloud](https://posit.cloud/) (online) OR
   - Install it via Chocolatey (first install R using `choco install r.project` and then RStudio using `choco install r.studio`) OR 
   - Install it via Homebrew.
+
+## Toolchain for building R packages
+
+If you are using RStudio, don't worry about setting this up for now. The IDE will alert you and provide support once you try to do something that requires you to setup your development environment. For example:
+
+  - On Windows, you will need to install [Rtools](https://r-pkgs.org/setup.html#windows).
+  - On macOS, you will need to install [Xcode](https://r-pkgs.org/setup.html#macos).
+  - On Linux, you will need to install the R development package, called [`r-base-dev`](https://r-pkgs.org/setup.html#linux).
 
 ## Selecting a package name
 
@@ -80,14 +80,20 @@ git push --set-upstream origin main
 ## Using `devtools::check()`
 
 - At this stage, you can try `devtools::check()` to see if there are any issues with the package.
-- It should raise an issue about missing/non-standard license in the `DESCRIPTION` file. It will be fixed soon!
+- If any of the toolchain required to build an R package is missing in your system, then RStudio will alert you at this stage. Please refer [Toolchain for building R packages](#Toolchain-for-building-R-packages) and once done run `devtools::check()` again. It should raise an issue about missing/non-standard license in the `DESCRIPTION` file (This issue will be fixed soon!).
 
 ## Update `DESCRIPTION` file
 
 - The `DESCRIPTION` file contains the metadata of your package. You can add some descriptive text about your package under `Title` and `Description` fields. You can also fill in the author and maintainer details. 
 - Manually add BSD-3-Clause license (recommended) first to your repository and then to the `DESCRIPTION` file.
 - Run `devtools::check()` to verify if everything works (As of now, it raises a note "Licence stub is invalid DCF.")
 
+## Build a README
+
+- Use `usethis::use_readme_rmd()` to initialize a basic, executable `README.Rmd` file. 
+- In the `README.Rmd` you can add the purpose of the package, provide installation instructions, and show an example of how the package can be used.
+- Remember to render the `README.Rmd` file (each time that you make a change to it) to make the `README.md` file. You can do this by running `devtools::build_readme()`.
+
 ## Add R files and corresponding unit tests
 
 - Create a R function file using `usethis::use_r("filename")`.
@@ -103,20 +109,42 @@ git push --set-upstream origin main
 - Put the cursor somewhere in the function definition. Then do, `Code > Insert roxygen skeleton`. A comment structure should appear above your function, in which each line begins with #'. 
 - Edit the comments suitably. If a `NAMESPACE` file already exists, please delete it so that it can be automatically generated by `roxygen2`. To do so, run `devtools::document()` this will also create the corresponding `filename.Rd` file in `man/filename.Rd` using `roxygen2`.
 
-## Build a README
-
-- Use `usethis::use_readme_rmd()` to initialize a basic, executable `README.Rmd` file. 
-- In the `README.Rmd` you can add the purpose of the package, provide installation instructions, and show an example of how the package can be used.
-- Remember to render the `README.Rmd` file to make the `README.md` file. You can do this by running `devtools::build_readme()`.
-
 ## Create website for your package
 
 - Run `install.packages("pkgdown")`.
 - To configure the package to use and deploy pkgdown, run `usethis::use_pkgdown_github_pages()`.
-- To preview your site locally before publishing, run `pkgdown::build_site()`.
 - This will add the necessary components and sets up GitHub Actions for automatic site building when deploying. 
+- To preview your site locally before publishing, run `pkgdown::build_site()`. If you see a warning that the "package is in use and will not be installed", then:
+
+  - Run `search()` to see if the package is loaded.
+  - If it is, run `detach("package:pkgname", unload = TRUE)` to unload it.
+  - Run `search()` again to verify that the package is no longer loaded.
+  - Then run `pkgdown::build_site()` again to preview the site locally.
+
 - Your `README.md` becomes the homepage, documentation in `man/` generates a function reference, and vignettes will be rendered into `articles/`.
 
+## Bonus!
+
+- Add a GitHub action workflow to render Rmarkdown using `usethis::use_github_action("render-rmarkdown")`.
+- Add another action to lint your package using `usethis::use_github_action("lint")`.
+- Add a `R CMD-check` badge using `usethis::use_github_actions_badge()`.
+- To add a package to the `DESCRIPTION` file, use `usethis::use_package("pkgname")`.
+- Customise the package website by editing the `_pkgdown.yml` file. For example, you can add a lightswitch and GitHub repository button to the navbar:
+
+```yaml
+template:
+  bootstrap: 5
+  light-switch: true
+navbar:
+  structure:
+    right: [search, github, lightswitch]
+  components:
+    github:
+      icon: fa-github
+      href: https://github.com/<owner-name>/<repo-name>
+      aria-label: GitHub
+```
+
 ## Installation
 
 You can install the development version of repositoryr from [GitHub](https://github.com/) with:

README.md

@@ -4,6 +4,8 @@
 # repositoryr
 
 <!-- badges: start -->
+
+[![R-CMD-check](https://github.com/ImperialCollegeLondon/repositoryr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ImperialCollegeLondon/repositoryr/actions/workflows/R-CMD-check.yaml)
 <!-- badges: end -->
 
 The goal of repositoryr is to provide a step by step guide to creating a
@@ -21,6 +23,19 @@ R package repository.
     `choco install r.studio`) OR
   - Install it via Homebrew.
 
+## Toolchain for building R packages
+
+If you are using RStudio, don’t worry about setting this up for now. The
+IDE will alert you and provide support once you try to do something that
+requires you to setup your development environment. For example:
+
+- On Windows, you will need to install
+  [Rtools](https://r-pkgs.org/setup.html#windows).
+- On macOS, you will need to install
+  [Xcode](https://r-pkgs.org/setup.html#macos).
+- On Linux, you will need to install the R development package, called
+  [`r-base-dev`](https://r-pkgs.org/setup.html#linux).
+
 ## Selecting a package name
 
 Install the package `available` in RStudio using
@@ -94,8 +109,13 @@ repo](https://happygitwithr.com/existing-github-last.html#create-and-connect-a-g
 
 - At this stage, you can try `devtools::check()` to see if there are any
   issues with the package.
-- It should raise an issue about missing/non-standard license in the
-  `DESCRIPTION` file. It will be fixed soon!
+- If any of the toolchain required to build an R package is missing in
+  your system, then RStudio will alert you at this stage. Please refer
+  [Toolchain for building R
+  packages](#Toolchain-for-building-R-packages) and once done run
+  `devtools::check()` again. It should raise an issue about
+  missing/non-standard license in the `DESCRIPTION` file (This issue
+  will be fixed soon!).
 
 ## Update `DESCRIPTION` file
 
@@ -108,6 +128,17 @@ repo](https://happygitwithr.com/existing-github-last.html#create-and-connect-a-g
 - Run `devtools::check()` to verify if everything works (As of now, it
   raises a note “Licence stub is invalid DCF.”)
 
+## Build a README
+
+- Use `usethis::use_readme_rmd()` to initialize a basic, executable
+  `README.Rmd` file.
+- In the `README.Rmd` you can add the purpose of the package, provide
+  installation instructions, and show an example of how the package can
+  be used.
+- Remember to render the `README.Rmd` file (each time that you make a
+  change to it) to make the `README.md` file. You can do this by running
+  `devtools::build_readme()`.
+
 ## Add R files and corresponding unit tests
 
 - Create a R function file using `usethis::use_r("filename")`.
@@ -133,29 +164,57 @@ repo](https://happygitwithr.com/existing-github-last.html#create-and-connect-a-g
   the corresponding `filename.Rd` file in `man/filename.Rd` using
   `roxygen2`.
 
-## Build a README
-
-- Use `usethis::use_readme_rmd()` to initialize a basic, executable
-  `README.Rmd` file.
-- In the `README.Rmd` you can add the purpose of the package, provide
-  installation instructions, and show an example of how the package can
-  be used.
-- Remember to render the `README.Rmd` file to make the `README.md` file.
-  You can do this by running `devtools::build_readme()`.
-
 ## Create website for your package
 
 - Run `install.packages("pkgdown")`.
+
 - To configure the package to use and deploy pkgdown, run
   `usethis::use_pkgdown_github_pages()`.
-- To preview your site locally before publishing, run
-  `pkgdown::build_site()`.
+
 - This will add the necessary components and sets up GitHub Actions for
   automatic site building when deploying.
+
+- To preview your site locally before publishing, run
+  `pkgdown::build_site()`. If you see a warning that the “package is in
+  use and will not be installed”, then:
+
+  - Run `search()` to see if the package is loaded.
+  - If it is, run `detach("package:pkgname", unload = TRUE)` to unload
+    it.
+  - Run `search()` again to verify that the package is no longer loaded.
+  - Then run `pkgdown::build_site()` again to preview the site locally.
+
 - Your `README.md` becomes the homepage, documentation in `man/`
   generates a function reference, and vignettes will be rendered into
   `articles/`.
 
+## Bonus!
+
+- Add a GitHub action workflow to render Rmarkdown using
+  `usethis::use_github_action("render-rmarkdown")`.
+- Add another action to lint your package using
+  `usethis::use_github_action("lint")`.
+- Add a `R CMD-check` badge using `usethis::use_github_actions_badge()`.
+- To add a package to the `DESCRIPTION` file, use
+  `usethis::use_package("pkgname")`.
+- Customise the package website by editing the `_pkgdown.yml` file. For
+  example, you can add a lightswitch and GitHub repository button to the
+  navbar:
+
+``` yaml
+template:
+  bootstrap: 5
+  light-switch: true
+navbar:
+  structure:
+    right: [search, github, lightswitch]
+  components:
+    github:
+      icon: fa-github
+      href: https://github.com/<owner-name>/<repo-name>
+      aria-label: GitHub
+```
+
 ## Installation
 
 You can install the development version of repositoryr from