vignettes

ropensci · Aug 1, 2023 · 040d747 · 040d747
1 parent 4316181
commit 040d747
Show file tree

Hide file tree

Showing 5 changed files with 149 additions and 16 deletions.
diff --git a/dev/building_envs_with_rix.Rmd b/dev/building_envs_with_rix.Rmd
@@ -214,3 +214,5 @@ specifically the code as it is in the `fusen` branch. The commit is also
 provided, to pin the exact version of the package needed. The `{fusen}` package
 is also installed, from the main branch at commit `d617172447d`.
 
+To learn more about using `{rix}` on a daily basis, read the [Interactive
+use](https://b-rodrigues.github.io/rix/articles/interactive-use.html) vignette.
diff --git a/dev/config_fusen.yaml b/dev/config_fusen.yaml
@@ -37,6 +37,19 @@ data_doc.Rmd:
     check: true
     document: true
     overwrite: 'yes'
+interactive_use.Rmd:
+  path: dev/interactive_use.Rmd
+  state: active
+  R: []
+  tests: []
+  vignettes: vignettes/interactive-use.Rmd
+  inflate:
+    flat_file: dev/interactive_use.Rmd
+    vignette_name: Interactive use
+    open_vignette: true
+    check: true
+    document: true
+    overwrite: 'yes'
 non_interactive_use.Rmd:
   path: dev/non_interactive_use.Rmd
   state: active

diff --git a/dev/interactive_use.Rmd b/dev/interactive_use.Rmd
@@ -10,29 +10,32 @@ editor_options:
 This vignette describes interactive use of environments built with `{rix}` using
 a GUI editor like RStudio. I will discuss two scenarios: one in which you
 already have R and RStudio installed on your operating system using the usual
-installation method for your operating system, and another in which you used
-Nix to install R and RStudio (or any other IDE).
+installation method for your operating system, and another in which you used Nix
+to install R and RStudio (or any other IDE).
 
 ## Scenario 1: you installed R and RStudio as usual
 
 Let's suppose that you are already running R and RStudio and that you wish to
 start using `{rix}` to define reproducible environments for your new projects
-henceforth. These environments will get built using the Nix package manager and
-will not only include the required R packages for your project but also a
-specific version of R. If you are used to using RStudio, then you also need to
-install RStudio using Nix. To run this project specific version of RStudio, you
-then need to activate the environment before running this project-specific
-version of RStudio. Suppose for example that you generated a `default.nix` file
-for a project called "kmeans", and suppose that this project is in the following
-path: `~/Documents/kmeans` (on Windows it would be something like
+starting today. These environments will get built using the Nix package manager
+and will not only include the required R packages for your project but also a
+specific version of R, and any required system-level dependency as well. If you
+are used to using RStudio, then you also need to install RStudio using Nix in
+these project-specific environments. To run a project-specific version of
+RStudio and R, you will first need to create a `default.nix` file and build the
+environment defined therein using Nix. Once this is done, you then need to
+activate the environment before running this project-specific version of
+RStudio. Suppose for example that you generated a `default.nix` file for a
+project called "kmeans", and suppose that this project is in the following path:
+`~/Documents/kmeans` (on Windows it would be something like
 `C:\Users\Billy\Documents\kmeans`). Navigate to that folder using your terminal,
-and then run `nix-shell`. You will then be *dropped into* a Nix shell. From there
-you can type `rstudio` to run this project specific version of RStudio with all
-the packages. You can then work on it as usual.
+and then run `nix-shell`. You will then be *dropped into* a Nix shell. From
+there you can type `rstudio` to run this project specific version of RStudio
+with all the packages. You can then work on it as usual.
 
 You can also define a shortcut to a project that will take care of activating
-the environment and launching rstudio. For example, you could define a bash alias
-like this:
+the environment and launching rstudio. For example, you could define a bash
+alias like this:
 
 ```
 alias kmeans='nix-shell ~/Documents/kmeans/default.nix --run rstudio
@@ -96,3 +99,10 @@ into an R console. From there you can start using `{rix}` to generate new and
 more complex environments.
 
 ## Other IDEs
+
+Visual Studio Code and Emacs have been tested and unlike RStudio, you can use
+the version of either VS Code or Emacs that you already have installed on your
+system. But there's nothing stopping you from installing a project-specific
+version of VS Code or Emacs as well. Configuration and settings should be
+accessible across every version from every environment, since these are globally
+defined at the level of your system.
diff --git a/vignettes/building-reproducible-development-environments-with-rix.Rmd b/vignettes/building-reproducible-development-environments-with-rix.Rmd
@@ -240,4 +240,6 @@ specifically the code as it is in the `fusen` branch. The commit is also
 provided, to pin the exact version of the package needed. The `{fusen}` package
 is also installed, from the main branch at commit `d617172447d`.
 
+To learn more about using `{rix}` on a daily basis, read the [Interactive
+use](https://b-rodrigues.github.io/rix/articles/interactive-use.html) vignette.
 
diff --git a/vignettes/interactive-use.Rmd b/vignettes/interactive-use.Rmd
@@ -18,7 +18,113 @@ knitr::opts_chunk$set(
 library(rix)
 ```
 
-<!-- WARNING - This vignette is generated by {fusen} from /dev/interactive_use.Rmd: do not edit by hand -->
+<!-- WARNING - This vignette is generated by {fusen} from dev/interactive_use.Rmd: do not edit by hand -->
 
 ## Introduction
 
+This vignette describes interactive use of environments built with `{rix}` using
+a GUI editor like RStudio. I will discuss two scenarios: one in which you
+already have R and RStudio installed on your operating system using the usual
+installation method for your operating system, and another in which you used Nix
+to install R and RStudio (or any other IDE).
+
+
+## Scenario 1: you installed R and RStudio as usual
+
+Let's suppose that you are already running R and RStudio and that you wish to
+start using `{rix}` to define reproducible environments for your new projects
+starting today. These environments will get built using the Nix package manager
+and will not only include the required R packages for your project but also a
+specific version of R, and any required system-level dependency as well. If you
+are used to using RStudio, then you also need to install RStudio using Nix in
+these project-specific environments. To run a project-specific version of
+RStudio and R, you will first need to create a `default.nix` file and build the
+environment defined therein using Nix. Once this is done, you then need to
+activate the environment before running this project-specific version of
+RStudio. Suppose for example that you generated a `default.nix` file for a
+project called "kmeans", and suppose that this project is in the following path:
+`~/Documents/kmeans` (on Windows it would be something like
+`C:\Users\Billy\Documents\kmeans`). Navigate to that folder using your terminal,
+and then run `nix-shell`. You will then be *dropped into* a Nix shell. From
+there you can type `rstudio` to run this project specific version of RStudio
+with all the packages. You can then work on it as usual.
+
+You can also define a shortcut to a project that will take care of activating
+the environment and launching rstudio. For example, you could define a bash
+alias like this:
+
+```
+alias kmeans='nix-shell ~/Documents/kmeans/default.nix --run rstudio
+```
+
+which would then execute RStudio in the right project by simply typing `kmeans`
+in a terminal. It's also possible to create an executable script that you can
+save in your PATH:
+
+```
+
+# !/usr/bin/env nix-shell
+
+# !nix-shell /home/Billy/Document/kmeans/default.nix -i bash
+
+rstudio
+```
+
+Name this script something like `kmeans_project`, make it executable (using
+`chmod +x kmeans_project`) and now you can run RStudio within this environment
+from anywhere.
+
+
+## Scenario 2: you install R and RStudio using Nix
+
+In case you don't have R installed, you cannot use the `{rix}` package to
+generate new expressions. In this case you might consider installing Nix first,
+and then using the expression below, which will install the latest development
+version of `{rix}` and R:
+
+```
+{ pkgs ? import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/8ad5e8132c5dcf977e308e7bf5517cc6cc0bf7d8.tar.gz") {} }:
+
+with pkgs;
+
+let
+  bootstrap_env = rWrapper.override {
+    packages = with rPackages; [
+
+    (buildRPackage {
+      name = "rix";
+      src = fetchgit {
+      url = "https://github.com/b-rodrigues/rix/";
+      branchName = "master";
+      rev = "935fb194b38adfb085a5bda9ebe5dc5bb504f2cb";
+      sha256 = "sha256-qMKcBcoemx3CcayA0Vt3LcDCAskhWyWXJBJVN8BaIOw=";
+      };
+    propagatedBuildInputs = [
+      httr
+      jsonlite
+    ];
+      })
+    ];
+  };
+in
+mkShell {
+  buildInputs = [bootstrap_env];
+  shellHook = "R";
+}
+
+```
+
+Save this into a `default.nix` file and run `nix-build` then `nix-shell` to drop
+into an R console. From there you can start using `{rix}` to generate new and
+more complex environments.
+
+
+## Other IDEs
+
+Visual Studio Code and Emacs have been tested and unlike RStudio, you can use
+the version of either VS Code or Emacs that you already have installed on your
+system. But there's nothing stopping you from installing a project-specific
+version of VS Code or Emacs as well. Configuration and settings should be
+accessible across every version from every environment, since these are globally
+defined at the level of your system.
+