feat(renvironments): clarify list dependencies section, explain minimum and specific version package installs, and other minor style tweaks (#85)

Author: amyheather

short_courses/r_environments.ipynb

@@ -299,14 +299,35 @@
     "\n",
     "#### 2. List dependencies\n",
     "\n",
-    "Dependencies can be listed as `Imports` (required packages) or `Suggests` (optional/development packages).\n",
+    "Dependencies can be listed as:\n",
+    "\n",
+    "* `Imports` (required packages).\n",
+    "* Suggests` (optional/development packages).\n",
     "\n",
     "For non-package projects, it's simplest to list all dependencies under `Imports`, which will be identified by `renv` (whilst those under `Suggests` may not unless used in scripts).\n",
     "\n",
     "`Suggests` is more relevant when constructing a package, as it distinguishes packages necessary only for optional features, vignettes or testing, from those required within the package itself.\n",
     "\n",
     "**Note:** In the [R Packages](https://r-pkgs.org/description.html) book, they recommend that - in `DESCRIPTION` - no versions are specified, or a minimum version is specified if you know that an older version of specific package/s would break the code. This is why it is important to also create an `renv.lock` file (as below), so you do have a record of the exact versions used.\n",
     "\n",
+    "Example `DESCRIPTION` with packages `dplyr` and `future`:\n",
+    "\n",
+    "```\n",
+    "Package: example\n",
+    "Title: Example DESCRIPTION\n",
+    "Version: 0.0.0.9000\n",
+    "Authors@R: \n",
+    "    person(\"Amy\", \"Heather\", , \"[email protected]\", role = c(\"aut\", \"cre\"))\n",
+    "Description: This is an example DESCRIPTION, used for environment management.\n",
+    "License: MIT + file LICENSE\n",
+    "Encoding: UTF-8\n",
+    "Roxygen: list(markdown = TRUE)\n",
+    "RoxygenNote: 7.0.0\n",
+    "Imports:\n",
+    "    dplyr\n",
+    "    future\n",
+    "```\n",
+    "\n",
     "#### 3. Install packages from `DESCRIPTION`\n",
     "\n",
     "Install packages listed in `DESCRIPTION` (and their dependencies) with:\n",
@@ -445,6 +466,19 @@
     "* Specify minimum or exact versions in your `DESCRIPTION` file.\n",
     "* Be aware that not all old versions are available for every R version; you may need to adjust your R version or accept a newer package.\n",
     "\n",
+    "To specify a minimum version in `DESCRIPTION`:\n",
+    "\n",
+    "```\n",
+    "Imports:\n",
+    "    dplyr (>= 1.0.0)\n",
+    "```\n",
+    "\n",
+    "To install a particular version using `renv` (which is then captured in `renv.lock` by calling `renv::snapshot()`):\n",
+    "\n",
+    "```\n",
+    "renv::install(\"[email protected]\")\n",
+    "```\n",
+    "\n",
     "#### Missing system dependencies\n",
     "\n",
     "Some R packages require external system libraries (e.g., C libraries, database clients) not installed by default.\n",
@@ -549,11 +583,11 @@
     "\n",
     "**Goal:** Clone a repository with a pre-configured `renv` environment, switch to the correct R version, restore dependencies, and run a basic R script.\n",
     "\n",
-    "Example repository: [amyheather/renv-reproduce-activity](https://github.com/amyheather/renv-reproduce-activity/)\n",
+    "**Repository:** [amyheather/renv-reproduce-activity](https://github.com/amyheather/renv-reproduce-activity/)\n",
     "\n",
     "```{dropdown} View solution\n",
     "\n",
-    "1. **Clone the example repository.**\n",
+    "1. **Clone the provided repository.**\n",
     "    * `git clone https://github.com/amyheather/renv-reproduce-activity.git`\n",
     "    * `cd renv-reproduce-activity`\n",
     "2. **Switch to the required R version.**\n",