docs: add docs for using renv in projects

Author: rokroskar

docs/docs/10-users/60-sessions/guides/00-environments/20-create-environment-with-custom-packages-installed.md

@@ -1,8 +1,11 @@
 # Create an environment with custom packages installed
 
-If you’d like a set of custom packages to be installed and ready to go when you (or anyone else) launches a session in your project, you can take advantage of Renku’s **code based environments**.
+If you’d like a set of custom packages to be installed and ready to go when you (or anyone else)
+launches a session in your project, you can take advantage of Renku’s **code based environments**.
 
-With Renku code based environments, you can point Renku to a code repository that contains an environment definition file, such as a `environment.yml`, `requirements.txt`, or `pyproject.toml`, and Renku will build a custom environment for your session for you!
+With Renku code based environments, you can point Renku to a code repository that contains an
+environment definition file, such as an `environment.yml`, `requirements.txt`, `pyproject.toml`, or
+`renv.lock`, and Renku will build a custom environment for your session for you!
 
 This guide has 2 parts:
 
@@ -13,15 +16,7 @@ This guide has 2 parts:
 
 ## What kinds of environment definitions are supported?
 
-RenkuLab’s code-based environments currently supports creating **Python** environments. Support for more languages is coming soon!
-
-:::tip
-
-Are you working in R? Support for R is coming soon. For now, for working with R please see
-[installing packages on the fly in your
-session](install-packages-on-the-fly-in-your-session).
-
-:::
+RenkuLab’s code-based environments currently support creating **Python** and **R** environments.
 
 ### Defining a Python Environment
 
@@ -144,13 +139,41 @@ Note that poetry version `1.8.3` will be used.
 
 </details>
 
-## Defining an R Environment
+### Defining an R Environment with renv
 
-:::info
+Renku can build an R environment from an [`renv`](https://rstudio.github.io/renv/) lockfile.
+`renv` records the R packages used by your project in `renv.lock`; Renku uses this lockfile to
+restore those packages when building the session image.
 
-This feature is coming soon. For now, please see [R](./install-packages-on-the-fly-in-your-session). ).
+To use `renv` with a code-based environment:
 
-:::
+1. In your R project, install and initialize `renv` if you have not already done so:
+
+   ```r
+   install.packages("renv")
+   renv::init()
+   ```
+
+2. Install the packages your project needs as usual, for example:
+
+   ```r
+   install.packages(c("dplyr", "ggplot2", "shiny"))
+   ```
+
+3. Snapshot the environment to update the lockfile:
+
+   ```r
+   renv::snapshot()
+   ```
+
+4. Commit `renv.lock` at the root (top level) of the code repository. You should also commit the
+   files created by `renv` that are meant to be shared with the project, such as `.Rprofile` and
+   `renv/activate.R`.
+
+When Renku builds the image, it restores the packages recorded in `renv.lock`. If a package requires
+system libraries that are not available in the build image, the build can fail. In that case,
+consider using a custom Docker image instead; see [How to use your own docker image for a Renku
+session](use-your-own-docker-image-for-renku-session).
 
 ## How to create a code-based environment for your Renku session
 
@@ -162,7 +185,8 @@ repository](create-environment-with-custom-packages-private-code-repository).
 
 :::
 
-1. Make sure the code repository that contains your environment definition file is added to your Renku project.
+1. Make sure the code repository that contains your environment definition file is added to your
+   Renku project.
 2. Create a **new session launcher**
 3. Select the **Create from code** option
 
@@ -184,8 +208,10 @@ repository](create-environment-with-custom-packages-private-code-repository).
 
    :::
 
-5. Select the **Environment** **type** (Python, _more coming soon_)
-6. Select the **User interface** you’d like your session to have (VSCodium or Jupyterlab, _more coming soon_).
+5. Select the **Environment type**. Choose **Python** for Python environment definition files,
+   or **R** for repositories that use `renv.lock`.
+6. Select the **User interface** you’d like your session to have, such as VSCodium/JupyterLab
+   for Python environments or RStudio for R environments.
 7. Click **Next**
 8. Define the **name** of the Session Launcher
 9. Select the default **compute resources**
@@ -199,7 +225,9 @@ When the environment is built, you can launch your session.
 
 ## Updating a code-based environment
 
-1. When you want to make changes to your environment (add new packages), first update the environment definition file in the code repository where the environment is defined.
+1. When you want to make changes to your environment (add new packages), first
+   update the environment definition file in the code repository where the
+   environment is defined.
 2. Then, rebuild the environment in RenkuLab:
    1. Click on the session launcher to open the session launcher side panel.
    2. Navigate to the **Session Environment** section.

docs/docs/10-users/60-sessions/guides/00-environments/25-create-environment-with-custom-packages-private-code-repository.md

@@ -1,14 +1,22 @@
 # Create an environment with custom packages from a private code repository (GitHub Actions)
 
-Would you like Renku to create an environment for you with the packages you need pre-installed? Renku can create a docker image for your Renku session for you based on a environment definition file in a code repository, such as a `environment.yml`, `requirements.txt`, or `pyproject.toml`.
+Would you like Renku to create an environment for you with the packages you need pre-installed?
+Renku can create a docker image for your Renku session for you based on an environment definition
+file in a code repository, such as an `environment.yml`, `requirements.txt`, `pyproject.toml`, or
+`renv.lock`.
 
-If your code repository is public, you can have Renku build this image directly as part of your project! See [How to create an environment with custom packages installed](create-environment-with-custom-packages-installed).
+If your code repository is public, you can have Renku build this image directly as part of your
+project! See [How to create an environment with custom packages
+installed](create-environment-with-custom-packages-installed).
 
-If your code repository is private, follow the instructions below.
+The instructions below are for _private_ code repositories that cannot use the
+automatic builds in RenkuLab.
 
 ## Create a GitHub action to build a docker image
 
-1. First, make sure your code repository meets the requirements for Renku to build an image for you. See [What kinds of environment definitions are supported?](create-environment-with-custom-packages-installed)
+1. First, make sure your code repository meets the requirements for Renku to build an image for you.
+   See [What kinds of environment definitions are
+   supported?](create-environment-with-custom-packages-installed)
 2. In your GitHub code repository, in the upper menu, click on **Actions**.
 
 <p class="image-container-l">
@@ -69,10 +77,14 @@ If your code repository is private, follow the instructions below.
              frontend: jupyterlab
    ```
 
-6. By default, the action defined above will create an image with JupyterLab as the front end. If you prefer a different front end, replace `jupyterlab` in the last line of the file with one of the following alternative front ends:
+6. By default, the action defined above will create an image with JupyterLab as
+   the front end. If you prefer a different front end, replace `jupyterlab` in
+   the last line of the file with one of the following alternative front ends:
    - `jupyterlab`: Web-based interactive development for Jupyter notebooks, code, and data.
    - `vscodium`: A freely-licensed version of Microsoft’s editor VS Code.
    - `ttyd`: A web-based terminal with a minimalist interface.
+   - `rstudio`: RStudio Server for R projects.
+
 7. Commit changes
 
 ## Add the built image to your Renku project

docs/docs/10-users/60-sessions/guides/00-environments/index.md

@@ -20,20 +20,25 @@ environment is right for you, answer the following questions:
 
 ### 1. What language are you working in?
 
-#### → I’m working in R
-
-Renku only has one mode for working with R sessions at the moment. When you create a session
-launcher, select **global environment** and select the **R** global environment. If you need to
-install additional packages, see [How to install packages on-the-fly in your
-session](install-packages-on-the-fly-in-your-session).
-
 #### → I’m working in Python
 
 We have multiple ways of working in Python in Renku sessions! Please continue to the next question
 [2. Would you like packages to be pre-installed and ready to go when you (or anyone else) launches
 the
 session?](#2-would-you-like-packages-to-be-pre-installed-and-ready-to-go-when-you-or-anyone-else-launches-the-session).
 
+#### → I’m working in R
+
+If your project uses [`renv`](https://rstudio.github.io/renv/) and has an `renv.lock` file,
+Renku can build a code-based environment with your packages pre-installed. See [How to create an
+environment with custom packages
+installed](create-environment-with-custom-packages-installed#defining-an-r-environment-with-renv).
+
+If you do not need packages pre-installed, create a session launcher with a **global environment**
+and select the **R** global environment. If you need to install additional packages temporarily, see
+[How to install packages on-the-fly in your
+session](install-packages-on-the-fly-in-your-session).
+
 #### → I’m working in another language
 
 Working in some other language? That’s ok! You can run a wide variety of Docker images in Renku
@@ -48,8 +53,8 @@ If you’d like a set of custom packages to be installed and ready to go when yo
 launches a session in your project, you can take advantage of Renku’s code based environments.
 
 With Renku code based environments, you can point Renku to a code repository that contains an
-environment definition file, such as a environment.yml, requirements.txt, or pyproject.toml, and
-Renku will build a custom environment for your session for you!
+environment definition file, such as `environment.yml`, `requirements.txt`, `pyproject.toml`, or
+`renv.lock`, and Renku will build a custom environment for your session for you!
 
 → If your code repository is **public**, see [How to create an environment with custom packages
 installed](create-environment-with-custom-packages-installed).