Merge pull request #108 from b-rodrigues/ropensci

Ropensci

.Rbuildignore

@@ -15,3 +15,4 @@
 ^Meta$
 ^default.nix$
 ^_debug_with_nix.R$
+^codemeta\.json$

CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing
+
+This package is developed using the `{fusen}` package. If you want to
+contribute, please edit the `.Rmd` files found in the `dev/` folder. Then,
+inflate the package using `fusen::inflate_all()`. If no errors are found
+(warning and notes are OK), then commit and open a PR. To learn how to use
+`{fusen}` (don't worry, it's super easy), refer to this
+[vignette](https://thinkr-open.github.io/fusen/articles/How-to-use-fusen.html).
+In our development workflow, we use [semantic versioning](https://semver.org)
+via [{fledge}](https://fledge.cynkra.com).
+
+## Discussions
+
+For general discussion about the package, open a discussion on <https://github.com/b-rodrigues/rix/discussions>.
+To submit bug reports or request features, open an issue <https://github.com/b-rodrigues/issues>.

R/find_rev.R

@@ -292,6 +292,19 @@ fetchpkgs  <- function(git_pkgs, archive_pkgs){
 #'   `options(rix.nix_locale_variables = list(LANG = "de_CH.UTF-8", <...>)`
 #'   and the aforementioned locale variable names.
 #' @export
+#' @examples
+#' \dontrun{
+#' # Build an environment with the latest version of R
+#' # and the dplyr and ggplot2 packages
+#' rix(r_ver = "latest",
+#'     r_pkgs = c("dplyr", "ggplot2"),
+#'     system_pkgs = NULL,
+#'     git_pkgs = NULL,
+#'     ide = "code",
+#'     project_path = path_default_nix,
+#'     overwrite = TRUE,
+#'     print = TRUE)
+#' }
 rix <- function(r_ver = "latest",
                 r_pkgs = NULL,
                 system_pkgs = NULL,
@@ -618,11 +631,15 @@ create_default_nix <- function(path = file.path("inst", "extdata",
 #'   with `options(rix.nix_build_max_jobs = <integer>)`. Once you call
 #'   `nix_build()` the flag will be propagated to the call of `nix-build`.
 #' @export
+#' @examples
+#' \dontrun{
+#'   nix_build()
+#' }
 nix_build <- function(project_path = ".",
                       exec_mode = c("blocking", "non-blocking")) {
   has_nix_build <- nix_build_installed() # TRUE if yes, FALSE if no
   nix_file <- file.path(project_path, "default.nix")
-  
+
   stopifnot(
     "`project_path` must be character of length 1." =
       is.character(project_path) && length(project_path) == 1L,
@@ -775,7 +792,7 @@ nix_build_exit_msg <- function(x) {
 #' adoption of Nix in the R community, particularly until RStudio in Nixpkgs is
 #' packaged for macOS. We recommend calling `rix::init()` prior to comparing R
 #' code ran between two software environments with `rix::with_nix()`.
-#' 
+#'
 #' @param project_path Character with the folder path to the isolated nix-R project. 
 #' Defaults to `"."`, which is the current working directory path. If the folder 
 #' does not exist yet, it will be created.
@@ -794,6 +811,17 @@ nix_build_exit_msg <- function(x) {
 #' `"verbose"`, which provides more detailed diagnostics.
 #' @export
 #' @seealso [with_nix()]
+#' @return Nothing, this function only has the side-effect of writing a file
+#'   called ".Rprofile" to the specified path.
+#' @examples
+#' \dontrun{
+#' # create an isolated, runtime-pure R setup via Nix
+#' project_path <- "./sub_shell"
+#' init(
+#'   project_path = project_path,
+#'   rprofile_action = "create_missing"
+#' )
+#' }
 init <- function(project_path = ".",
                  rprofile_action = c("create_missing", "create_backup",
                    "overwrite", "append"),

R/tar_nix_ga.R

@@ -8,6 +8,10 @@
 #' sure to give read and write permissions to the Github Actions bot.
 #' @return Nothing, copies file to a diretory.
 #' @export
+#' @examples
+#' \dontrun{
+#'   tar_nix_ga()
+#' }
 tar_nix_ga <- function(){
   # Add an empty .gitignore file if there isn’t any
 

README.Rmd

@@ -77,6 +77,23 @@ expressions. This means that you can generate expressions on a system on which
 you cannot easily install software, and then use these expressions on the cloud
 or on a CI/CD environment to build the project there.
 
+Here is an example of how to define an environment "as code" using `rix()`:
+
+```{r, eval = F}
+rix(r_ver = "latest",
+    r_pkgs = c("dplyr", "ggplot2"),
+    system_pkgs = NULL,
+    git_pkgs = NULL,
+    ide = "code",
+    project_path = path_default_nix,
+    overwrite = TRUE,
+    print = TRUE)
+```
+
+This generates a file called `default.nix` in the path `path_default_nix` with
+the correct expression to build this environment. To build the environment,
+the Nix package manager must be installed.
+
 ## Quick start for returning users
 
 *If you are not familiar with Nix or `{rix}` skip to the next section.*

README.md

@@ -79,6 +79,25 @@ expressions. This means that you can generate expressions on a system on
 which you cannot easily install software, and then use these expressions
 on the cloud or on a CI/CD environment to build the project there.
 
+Here is an example of how to define an environment “as code” using
+`rix()`:
+
+``` r
+rix(r_ver = "latest",
+    r_pkgs = c("dplyr", "ggplot2"),
+    system_pkgs = NULL,
+    git_pkgs = NULL,
+    ide = "code",
+    project_path = path_default_nix,
+    overwrite = TRUE,
+    print = TRUE)
+```
+
+This generates a file called `default.nix` in the path
+`path_default_nix` with the correct expression to build this
+environment. To build the environment, the Nix package manager must be
+installed.
+
 ## Quick start for returning users
 
 *If you are not familiar with Nix or `{rix}` skip to the next section.*

codemeta.json

@@ -0,0 +1,147 @@
+{
+  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
+  "@type": "SoftwareSourceCode",
+  "identifier": "rix",
+  "description": "Provides helper functions to create reproducible development environments using the Nix package manager.",
+  "name": "rix: Rix: Reproducible Environments With Nix",
+  "codeRepository": "https://github.com/b-rodrigues/rix",
+  "issueTracker": "https://github.com/b-rodrigues/rix",
+  "license": "https://spdx.org/licenses/GPL-3.0",
+  "version": "0.5.1.9000",
+  "programmingLanguage": {
+    "@type": "ComputerLanguage",
+    "name": "R",
+    "url": "https://r-project.org"
+  },
+  "runtimePlatform": "R version 4.3.2 (2023-10-31)",
+  "author": [
+    {
+      "@type": "Person",
+      "givenName": "Bruno",
+      "familyName": "Rodrigues",
+      "email": "bruno@brodrigues.co",
+      "@id": "https://orcid.org/0000-0002-3211-3689"
+    },
+    {
+      "@type": "Person",
+      "givenName": "Philipp",
+      "familyName": "Baumann",
+      "email": "baumann-philipp@protonmail.com",
+      "@id": "https://orcid.org/0000-0002-3194-8975"
+    }
+  ],
+  "maintainer": [
+    {
+      "@type": "Person",
+      "givenName": "Bruno",
+      "familyName": "Rodrigues",
+      "email": "bruno@brodrigues.co",
+      "@id": "https://orcid.org/0000-0002-3211-3689"
+    }
+  ],
+  "softwareSuggestions": [
+    {
+      "@type": "SoftwareApplication",
+      "identifier": "knitr",
+      "name": "knitr",
+      "provider": {
+        "@id": "https://cran.r-project.org",
+        "@type": "Organization",
+        "name": "Comprehensive R Archive Network (CRAN)",
+        "url": "https://cran.r-project.org"
+      },
+      "sameAs": "https://CRAN.R-project.org/package=knitr"
+    },
+    {
+      "@type": "SoftwareApplication",
+      "identifier": "rmarkdown",
+      "name": "rmarkdown",
+      "provider": {
+        "@id": "https://cran.r-project.org",
+        "@type": "Organization",
+        "name": "Comprehensive R Archive Network (CRAN)",
+        "url": "https://cran.r-project.org"
+      },
+      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
+    },
+    {
+      "@type": "SoftwareApplication",
+      "identifier": "testthat",
+      "name": "testthat",
+      "provider": {
+        "@id": "https://cran.r-project.org",
+        "@type": "Organization",
+        "name": "Comprehensive R Archive Network (CRAN)",
+        "url": "https://cran.r-project.org"
+      },
+      "sameAs": "https://CRAN.R-project.org/package=testthat"
+    }
+  ],
+  "softwareRequirements": {
+    "1": {
+      "@type": "SoftwareApplication",
+      "identifier": "R",
+      "name": "R",
+      "version": ">= 2.10"
+    },
+    "2": {
+      "@type": "SoftwareApplication",
+      "identifier": "codetools",
+      "name": "codetools",
+      "provider": {
+        "@id": "https://cran.r-project.org",
+        "@type": "Organization",
+        "name": "Comprehensive R Archive Network (CRAN)",
+        "url": "https://cran.r-project.org"
+      },
+      "sameAs": "https://CRAN.R-project.org/package=codetools"
+    },
+    "3": {
+      "@type": "SoftwareApplication",
+      "identifier": "httr",
+      "name": "httr",
+      "provider": {
+        "@id": "https://cran.r-project.org",
+        "@type": "Organization",
+        "name": "Comprehensive R Archive Network (CRAN)",
+        "url": "https://cran.r-project.org"
+      },
+      "sameAs": "https://CRAN.R-project.org/package=httr"
+    },
+    "4": {
+      "@type": "SoftwareApplication",
+      "identifier": "jsonlite",
+      "name": "jsonlite",
+      "provider": {
+        "@id": "https://cran.r-project.org",
+        "@type": "Organization",
+        "name": "Comprehensive R Archive Network (CRAN)",
+        "url": "https://cran.r-project.org"
+      },
+      "sameAs": "https://CRAN.R-project.org/package=jsonlite"
+    },
+    "5": {
+      "@type": "SoftwareApplication",
+      "identifier": "sys",
+      "name": "sys",
+      "provider": {
+        "@id": "https://cran.r-project.org",
+        "@type": "Organization",
+        "name": "Comprehensive R Archive Network (CRAN)",
+        "url": "https://cran.r-project.org"
+      },
+      "sameAs": "https://CRAN.R-project.org/package=sys"
+    },
+    "6": {
+      "@type": "SoftwareApplication",
+      "identifier": "utils",
+      "name": "utils"
+    },
+    "SystemRequirements": null
+  },
+  "fileSize": "194.622KB",
+  "relatedLink": "https://b-rodrigues.github.io/rix/",
+  "releaseNotes": "https://github.com/b-rodrigues/rix/blob/master/NEWS.md",
+  "readme": "https://github.com/b-rodrigues/rix/blob/master/README.md",
+  "contIntegration": ["https://github.com/b-rodrigues/rix/actions/workflows/R-CMD-check.yaml", "https://github.com/b-rodrigues/rix/actions?query=workflow%3Apkgcheck"]
+}

dev/0-dev_history.Rmd

@@ -33,6 +33,13 @@ usethis::use_gpl3_license()
 
 ```
 
+Add codemeta file:
+
+```{r, eval = F}
+codemetar::write_codemeta()
+
+```
+
 # All-in-one function to deploy publicly on GitHub
 
 Either use this GitHub all-in-one function or choose the steps one-by-one in the following sections.

dev/flat_build_envs.Rmd

@@ -378,6 +378,19 @@ you use another IDE, you can leave the "ide" argument blank:
 #'   `options(rix.nix_locale_variables = list(LANG = "de_CH.UTF-8", <...>)`
 #'   and the aforementioned locale variable names.
 #' @export
+#' @examples
+#' \dontrun{
+#' # Build an environment with the latest version of R
+#' # and the dplyr and ggplot2 packages
+#' rix(r_ver = "latest",
+#'     r_pkgs = c("dplyr", "ggplot2"),
+#'     system_pkgs = NULL,
+#'     git_pkgs = NULL,
+#'     ide = "code",
+#'     project_path = path_default_nix,
+#'     overwrite = TRUE,
+#'     print = TRUE)
+#' }
 rix <- function(r_ver = "latest",
                 r_pkgs = NULL,
                 system_pkgs = NULL,
@@ -714,11 +727,15 @@ session.
 #'   with `options(rix.nix_build_max_jobs = <integer>)`. Once you call
 #'   `nix_build()` the flag will be propagated to the call of `nix-build`.
 #' @export
+#' @examples
+#' \dontrun{
+#'   nix_build()
+#' }
 nix_build <- function(project_path = ".",
                       exec_mode = c("blocking", "non-blocking")) {
   has_nix_build <- nix_build_installed() # TRUE if yes, FALSE if no
   nix_file <- file.path(project_path, "default.nix")
-  
+
   stopifnot(
     "`project_path` must be character of length 1." =
       is.character(project_path) && length(project_path) == 1L,
@@ -876,7 +893,7 @@ via Nix
 #' adoption of Nix in the R community, particularly until RStudio in Nixpkgs is
 #' packaged for macOS. We recommend calling `rix::init()` prior to comparing R
 #' code ran between two software environments with `rix::with_nix()`.
-#' 
+#'
 #' @param project_path Character with the folder path to the isolated nix-R project. 
 #' Defaults to `"."`, which is the current working directory path. If the folder 
 #' does not exist yet, it will be created.
@@ -895,6 +912,17 @@ via Nix
 #' `"verbose"`, which provides more detailed diagnostics.
 #' @export
 #' @seealso [with_nix()]
+#' @return Nothing, this function only has the side-effect of writing a file
+#'   called ".Rprofile" to the specified path.
+#' @examples
+#' \dontrun{
+#' # create an isolated, runtime-pure R setup via Nix
+#' project_path <- "./sub_shell"
+#' init(
+#'   project_path = project_path,
+#'   rprofile_action = "create_missing"
+#' )
+#' }
 init <- function(project_path = ".",
                  rprofile_action = c("create_missing", "create_backup",
                    "overwrite", "append"),

dev/flat_cicd.Rmd

@@ -30,6 +30,10 @@ The function below copies a Github actions workflow file into the
 #' sure to give read and write permissions to the Github Actions bot.
 #' @return Nothing, copies file to a diretory.
 #' @export
+#' @examples
+#' \dontrun{
+#'   tar_nix_ga()
+#' }
 tar_nix_ga <- function(){
   # Add an empty .gitignore file if there isn’t any