diff --git a/docs/container_setup/github_codespace/creating_codespace.md b/docs/container_setup/github_codespace/creating_codespace.md
index 5fc0908d..09179d33 100644
--- a/docs/container_setup/github_codespace/creating_codespace.md
+++ b/docs/container_setup/github_codespace/creating_codespace.md
@@ -1,21 +1,30 @@
+# Creating a GitHub Codespace
+
+Follow these steps to create a new codespace:
+
+1. Navigate to the [r-dev-env repo](https://github.com/r-devel/r-dev-env)
+2. Click 'Open in GitHub Codespaces'
+3. Click 'Create Codespace'
-1. From the main branch of the [r-dev-env
-repo](https://github.com/r-devel/r-dev-env/tree/main), click on the 'Open in
-GitHub Codespaces' button and then click the green 'Create Codespace' button.
- !!! Note You will see the message "Codespace usage for this repository is
- paid for by ...", with your username. Don't panic!
+!!! Note "About Codespace Billing"
+ You will see "Codespace usage for this repository is paid for by [user]".
+ Don't worry!
+
+ - GitHub Codespaces: 120 core hours free per month
+ - Free hours = 120 / number of cores
+ - Default: 4 cores = 30 hours free per month
+ - Core count can be adjusted
- GitHub Codespaces offers 120 core hours of free usage per month for every GitHub user. So the actual number of free hours is 120 divided by the number of cores you are using to run your codespaces.
- For the r-dev-env codespace we have set the codespace usage to 4 cores which leads to 30hrs of free usage per month. This can be changed according to your preference.
+ **Resources:**
+ - [Billing Docs](https://github.com/features/codespaces)
+ - [Pricing Calculator](https://github.com/pricing/calculator)
+ - [Billing Page](https://github.com/settings/billing)
- For more details about codespaces billing, see the [Codespaces Billing Docs](https://github.com/features/codespaces).
- You can calculate your GitHub services usage with the [GitHub Services
- Pricing Calculator](https://github.com/pricing/calculator) and check your usage allowance under "Codespaces" on your [GitHub Billing page](https://github.com/settings/billing).
+## Setup
-2. The codespace setup screen will then be shown. Starting the container may
- take a minute or so.
+1. Wait for codespace setup (about 1 minute)
+2. You'll be redirected to VSCode:
-3. You will be taken to a VSCode editor within your browser.
diff --git a/docs/tutorials/building_r.md b/docs/tutorials/building_r.md
index 85f68146..43e036a4 100644
--- a/docs/tutorials/building_r.md
+++ b/docs/tutorials/building_r.md
@@ -1,133 +1,112 @@
-<!-- markdownlint-disable MD036 -->
-**1) Environment variables**
+# Building R from Source
-- We have environment variables defining paths to directories for building R and
- storing the source code.
-- `BUILDDIR` defines the build directory: `/workspaces/r-dev-env/build/r-devel`.
-- `TOP_SRCDIR` defines the source directory: `/workspaces/r-dev-env/svn/r-devel`
-- The environment variables are set in the codespace image and are available
- when the codespace starts.
+## 1. Environment Variables
- 
+The following environment variables define paths for building R:
-**2) svn checkout**
+- `BUILDDIR`: `/workspaces/r-dev-env/build/r-devel`
+- `TOP_SRCDIR`: `/workspaces/r-dev-env/svn/r-devel`
-- The svn checkout command lets us create a local copy of a specific tag/branch
- of a repository.
-- We can check out the latest version of the trunk (the main branch) of the R
- sources to $TOP_SRCDIR as follows:
+These variables are set in the codespace image and available at startup.
- ```bash
- svn checkout https://svn.r-project.org/R/trunk/ $TOP_SRCDIR
- ```
+## 2. SVN Checkout
-- Output : We get file structure something like this after checking out R source
- code from R svn repository.
+Get a local copy of R source code from the repository:
- 
+```console
+$ svn checkout https://svn.r-project.org/R/trunk/ $TOP_SRCDIR
+A trunk/COPYING
+A trunk/INSTALL
+...
+Checked out revision 86543.
+```
-**3) Download recommended packages for R**
+## 3. Download Packages
-To build R with the recommended packages, we need to run the
-`tools/rsync-recommended` script from the source directory to download the
-source code for these packages:
+Get recommended packages:
-```bash
-$TOP_SRCDIR/tools/rsync-recommended
+```console
+$ $TOP_SRCDIR/tools/rsync-recommended
+downloading recommended packages
+trying URL 'https://cran.r-project.org/src/contrib/Recommended/MASS_7.3-60.tar.gz'
+...
+** building package indices
+** testing if installed package can be loaded from temporary location
+** testing if installed package can be loaded from final location
+** testing if installed package keeps a record of temporary installation path
+* DONE
```
-
+## 4. Set Up Build Directory
-**4) Change to the build directory**
+Keep source directory clean by using a separate build directory:
-- To keep the source directory clean, we change to a build directory to
- configure and build R.
+1. Create build directory:
-- First create the directory specified by the BUILDDIR environment variable.
-
-```bash
-mkdir -p $BUILDDIR
-```
+ ```bash
+ mkdir -p $BUILDDIR
+ ```
-- Then we can change directory from root to the build directory.
+2. Change to build directory:
-```bash
-cd $BUILDDIR
-```
+ ```bash
+ cd $BUILDDIR
+ ```
-**5) Configure the build**
+## 5. Configure the Build
-- After we change directory, we must run the configure script from the source
-directory. This step takes ~1 minute on the codespace.
-
-```bash
-$TOP_SRCDIR/configure --with-valgrind-instrumentation=1
+Run configure (~1 minute):
+```console
+$ $TOP_SRCDIR/configure --with-valgrind-instrumentation=1
+checking build system type... x86_64-pc-linux-gnu
+checking host system type... x86_64-pc-linux-gnu
+...
+config.status: creating po/Makefile
+config.status: creating src/include/config.h
```
-<!-- markdownlint-disable MD046 -->
!!! Note
- The `--with-valgrind-instrumentation` option is set to 1 for effective use
- of valgrind. See the [Using
- valgrind](https://cran.r-project.org/doc/manuals/R-exts.html#Using-valgrind)
- section of the R-admin manual for more information.
-<!-- markdownlint-enable MD046 -->
-
-- The configure cmd prepares for building R, creating files and folders inside
- the BUILDDIR directory.
-- Output : We get file structure something like this after using configure
- command.
+ The `--with-valgrind-instrumentation` option enables effective use of
+ valgrind. See the [docs](https://cran.r-project.org/doc/manuals/R-exts.html#Using-valgrind)
+ for details.
- 
+## 6. Build R
-**6) Build R**
-
-Having configured R, we run `make` to build R. This take 5-10 minutes on the
-codespace.
+Build R (5-10 minutes):
```bash
make
```
-**7) Check R**
+## 7. Run Tests
-Check that the build of R passes R's standard checks:
+Run standard tests:
```bash
make check
```
-This takes a couple of minutes in the codespace. The check will stop with a
-error message if any of the tests fail. If this happens, see [SVN
-Help](./svn_help.md) for how to revert to a version that passes check.
+If tests fail, see [SVN Help](./svn_help.md).
-**8) Make R terminals use the built R**
+## 8. Configure R Terminal
-Run the `which_r` script to set which R to use for R terminals in VSCode. When
-prompted, enter the number corresponding to `r-devel`
+Set R version for VSCode:
-```bash
-which_r
-```
-
-```bash
+```console
+$ which_r
Which version of R should be used in new R terminals?
- 1. R 4.4.0 (release version built into this container)
- Additional R builds available:
- 2. r-devel
+1. R 4.4.0 (release version built into this container)
+Additional R builds available:
+ 2. r-devel
Enter the number corresponding to the selected version:
```
-This means that new R terminals will use the version of R you have just
-built![^1]
+Select `r-devel` to use your built version.[^1]
-[^1]: To switch back to the release version, run `which_r` and type `1`. The
-selected version is saved in the VSCode settings, so will be saved when you stop
-and restart the codespace.
+[^1]: To switch back to release version, run `which_r` and select `1`.
+ Selection persists across restarts.
-**9) Make contributions**
+## 9. Next Steps
-- After having built the current development version of R, we can now make
- changes to the source code and contribute to the project.
-- Follow the [R Contribution Workflow](./contribution_workflow.md) tutorial to
- learn how to do this.
+Start contributing! Follow the [R Contribution Workflow](./contribution_workflow.md).
diff --git a/docs/tutorials/contribution_workflow.md b/docs/tutorials/contribution_workflow.md
index 44f85846..c11fd5d9 100644
--- a/docs/tutorials/contribution_workflow.md
+++ b/docs/tutorials/contribution_workflow.md
@@ -1,48 +1,48 @@
-#### 1. Example Contribution Workflow using the R Dev Container
+# Example Contribution Workflow using the R Dev Container
-- To start working in R we will click on `R:(not attach)` which is in the bottom
- right of the VSCode window. This will open an R terminal for us.
+## 1. Starting R
- 
+- To start working in R, click on `R:(not attach)` in the bottom right of
+ VSCode. This will open an R terminal.
- 
+
-- We can now run R commands. We will use the `utils::askYesNo()` function as an
- example
+
- 
+- We can now run R commands. We will use the `utils::askYesNo()` function as
+ an example:
```R
- > askYesNo("Is this a good example?")
- Is this a good example? (Yes/no/cancel) Yes
- [1] TRUE
+> askYesNo("Is this a good example?")
+Is this a good example? (Yes/no/cancel) Yes
+[1] TRUE
```
-#### 2. Editing Source Code
+## 2. Editing Source Code
-- Edit the source code of `utils::askYesNo()` to change the default options. The
- source code can be found in `$TOP_SRCDIR/src/library/utils/R/askYesNo.R`.
-- You can redirect to that file using
+- Edit the source code of `utils::askYesNo()` to change the default options.
+ The source code is in `$TOP_SRCDIR/src/library/utils/R/askYesNo.R`.
+- You can redirect to that file using:
```bash
code $TOP_SRCDIR/src/library/utils/R/askYesNo.R
```
-**> Before edit:** 
+### Before and After Edit
+
+#### Before edit
```R title="askYesNo.R" linenums="20"
- prompts = getOption("askYesNo", gettext(c("Yes", "No", "Cancel"))),
+prompts = getOption("askYesNo", gettext(c("Yes", "No", "Cancel"))),
```
-**> With edit (for example - change to whatever you like!):**
-
-
+#### After edit
```R title="askYesNo.R" linenums="20"
- prompts = getOption("askYesNo", gettext(c("Oh yeah!", "Don't think so", "Cancel"))),
+prompts = getOption("askYesNo", gettext(c("Oh yeah!", "Don't think so", "Cancel"))),
```
-#### 3. Rebuild R
+## 3. Rebuilding R
- We can re-build R with our changes. Since we have only modified the utils
package, rebuilding R will only re-build the utils package.
@@ -61,21 +61,17 @@ cd $BUILDDIR
make
```
-
-
-- Optionally run `make check` to run R's test suite with your local changes. You
- may skip this step while you are iterating on a bug fix or other development,
+- Optionally run `make check` to run R's test suite with your local changes.
+ You may skip this step while iterating on a bug fix or other development,
until you are ready to [create a patch](./patch_update.md).
- To use the re-built R, simply open a new R terminal.
-#### 4. Cross check and Re-running Code
+## 4. Cross-checking Changes
-- Check the edit has worked as expected by re-running the example code: 
+- Check the edit has worked as expected by re-running the example code:
```R
- > askYesNo("Is this a good example?")
- Is this a good example? (Oh yeah!/don't think so/cancel) Oh yeah!
- [1] TRUE
-```
+> askYesNo("Is this a good example?")
+Is this a good example? (Oh yeah!/don't think so/cancel) Oh yeah!
+[1] TRUE
diff --git a/docs/tutorials/running_r.md b/docs/tutorials/running_r.md
index 0d31d242..adf918e5 100644
--- a/docs/tutorials/running_r.md
+++ b/docs/tutorials/running_r.md
@@ -1,20 +1,24 @@
+1. Create a file in VS Code ending with a .R extension. You can create new files
+ by clicking on the new file icon in VS Code Explorer, or use the `code` command
+ in the terminal to create and open an R file:
-1) Create a file in VS Code ending with a .R extension. You can create new files
-by clicking on the new file icon in VS Code Explorer, or use the `code` command
-in the terminal to create and open an R file
-
-```bash
-code R/test.R
+```console
+de R/test.R
```
-
+2. You should see `R:(not attached)` in the Status Bar at the bottom of the
+ VSCode window. Click on the `R:(not attached)` link to launch an R terminal.
-2) You should see `R:(not attached)` in the Status Bar at the bottom of the
-VSCode window.
+3. You can then send code from the `.R` file to the R terminal. For example:
-
+```R
+# In test.R
+print("Hello R Development!")
+```
-3) Click on the `R:(not attached)` link to launch an R terminal. You can then
-send code from the `.R` file to the R terminal by pressing `cmd/ctrl + enter`.
+```Rconsole
+> print("Hello R Development!")
+[1] "Hello R Development!"
+```
- 
+You can send code from the editor to the R terminal by pressing `cmd/ctrl + enter`.
diff --git a/docs/tutorials/update_source.md b/docs/tutorials/update_source.md
index b052c093..9cd10e63 100644
--- a/docs/tutorials/update_source.md
+++ b/docs/tutorials/update_source.md
@@ -1,56 +1,64 @@
+# Updating R Source Code
+
The R Core Team commit changes to the development version of R sometimes
multiple times a day. It's a good idea to update your local copy of the source
code from time to time, especially before creating a patch. To do so, follow
these steps:
-#### 1) Close R terminal
+## 1. Close R Terminal
If you have an R terminal open, quit R or close the terminal.
-#### 2) Go to the source directory
+## 2. Go to the Source Directory
-In a bash terminal, change to the source directory
+In a bash terminal, change to the source directory:
```bash
cd $TOP_SRCDIR
```
-#### 3) Review local changes
+## 3. Review Local Changes
-Use the Subversion diff command to review changes you have made to source code
+Use the Subversion diff command to review changes you have made to source code:
```bash
svn diff
```
-#### 4) Revert changes (optional)
+## 4. Revert Changes (Optional)
If you no longer want to keep your local changes, you can revert them.
-Revert the changes made in specific file
+### Revert Specific Files
+
+To revert changes made in a specific file:
```bash
svn revert src/library/utils/R/askYesNo.R
```
-Revert changes in a directory
+### Revert Directories
+
+To revert changes in a directory:
```bash
svn revert src/lib/utils
```
-Revert all local changes
+### Revert All Changes
+
+To revert all local changes:
```bash
svn revert -R .
```
-#### 5) Rebuild and check with any local changes
+## 5. Rebuild and Check Local Changes
If you have no local changes remaining, skip to the next step.
Otherwise, go to the build directory to build and check R with your local
-changes.
+changes:
```bash
cd $BUILDDIR
@@ -60,25 +68,25 @@ make check
If the check fails with an error, you have broken something with your local
changes. Fix this before proceeding. Otherwise go back to the source directory
-to continue
+to continue:
```bash
cd $TOP_SRCDIR
```
-#### 6) Update using svn
+## 6. Update Using SVN
Use the Subversion command `update` to update your local copy with the latest
-changes by the R Core Team.
+changes by the R Core Team:
```bash
svn update
```
-#### 7) Rebuild and check with the updates
+## 7. Rebuild and Check Updates
To rebuild R with the latest changes from the R Core Team and any local changes
-you have kept, go to the build directory to build and check R
+you have kept:
```bash
cd $BUILDDIR
diff --git a/mkdocs.yml b/mkdocs.yml
index 29cd96a9..e6f77ce8 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,81 +1,109 @@
-site_name: R Devel Container Docs
-repo_name: r-devel/r-dev-env
+site_name: R Development Environment
+site_url: https://r-devel.github.io/r-dev-env/
repo_url: https://github.com/r-devel/r-dev-env
-nav:
- - 'Home': 'index.md'
- - 'Container Setup':
- - 'Overview': 'container_setup/index.md'
- - 'Github Codespace':
- - 'Starting Codespace': 'container_setup/github_codespace/creating_codespace.md'
- - 'Stopping and Restarting' : 'container_setup/github_codespace/codespacestartstop.md'
- - 'Collaborating with Live Share' : 'container_setup/github_codespace/live_share.md'
- - 'Gitpod Workspace':
- - 'Start Workspace': 'container_setup/gitpod_workspace/workspacestart.md'
- - 'Stopping and Restarting' : 'container_setup/gitpod_workspace/workspacestop_and_restart.md'
- - 'Collaborating with Live Share' : 'container_setup/gitpod_workspace/live_share.md'
- - 'Local Setup' :
- - 'Docker': 'container_setup/local_setup/localsetup.md'
- - 'Tutorials':
- - 'Running R' : 'tutorials/running_r.md'
- - 'Building R': 'tutorials/building_r.md'
- - 'R Contribution Workflow' : 'tutorials/contribution_workflow.md'
- - 'Updating Source Code' : 'tutorials/update_source.md'
- - 'Creating a Patch File' : 'tutorials/patch_update.md'
- - 'Multiple R Versions' : 'tutorials/multi_r_compilation.md'
- - 'SVN Help' : 'tutorials/svn_help.md'
- - 'Contributor Guide' :
- - 'contributor_guide/contributing_to_docs.md'
- - 'contributor_guide/contributing_to_codebase.md'
- - 'Resources' : 'resources.md'
- - 'Troubleshooting Info' : 'troubleshoot.md'
+repo_name: r-devel/r-dev-env
+edit_uri: edit/main/docs/
+
theme:
name: material
features:
- - navigation.tabs
+ - navigation.instant
+ - navigation.tracking
- navigation.sections
- - toc.integrate
+ - navigation.expand
+ - navigation.indexes
- navigation.top
- - search.suggest
- - search.highlight
- - content.tabs.link
- - content.code.annotation
+ - toc.follow
- content.code.copy
-
-
+ - content.code.annotate
palette:
- - scheme: default
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
+ primary: indigo
+ accent: indigo
toggle:
icon: material/brightness-7
name: Switch to dark mode
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
primary: indigo
- accent: blue
- - scheme: slate
+ accent: indigo
toggle:
icon: material/brightness-4
name: Switch to light mode
- primary: indigo
- accent: blue
plugins:
- - social
-
-extra:
- social:
- - icon: fontawesome/brands/github
- link: https://github.com/r-devel/r-dev-env/
- - icon: fontawesome/brands/slack
- link: https://r-contributors.slack.com/
+ - search
+ - git-revision-date-localized:
+ enable_creation_date: true
+ type: timeago
markdown_extensions:
- - pymdownx.highlight:
- anchor_linenums: true
- - pymdownx.inlinehilite
- - pymdownx.snippets
+ - abbr
- admonition
+ - attr_list
+ - def_list
+ - footnotes
+ - md_in_html
+ - toc:
+ permalink: true
+ toc_depth: 3
- pymdownx.arithmatex:
generic: true
- - footnotes
+ - pymdownx.betterem:
+ smart_enable: all
+ - pymdownx.caret
- pymdownx.details
- - pymdownx.superfences
+ - pymdownx.emoji:
+ emoji_generator: material.extensions.emoji.to_svg
+ emoji_index: material.extensions.emoji.twemoji
+ - pymdownx.highlight:
+ anchor_linenums: true
+ line_spans: __span
+ pygments_lang_class: true
+ - pymdownx.inlinehilite
+ - pymdownx.keys
+ - pymdownx.magiclink:
+ repo_url_shorthand: true
+ user: r-devel
+ repo: r-dev-env
- pymdownx.mark
- - attr_list
+ - pymdownx.smartsymbols
+ - pymdownx.superfences:
+ custom_fences:
+ - name: mermaid
+ class: mermaid
+ format: pymdownx.superfences.fence_code_format
+ - pymdownx.tabbed:
+ alternate_style: true
+ - pymdownx.tasklist:
+ custom_checkbox: true
+ - pymdownx.tilde
+
+nav:
+ - Home: index.md
+ - Container Setup:
+ - container_setup/index.md
+ - GitHub Codespace:
+ - container_setup/github_codespace/creating_codespace.md
+ - container_setup/github_codespace/codespacestartstop.md
+ - container_setup/github_codespace/live_share.md
+ - Gitpod Workspace:
+ - container_setup/gitpod_workspace/workspacestart.md
+ - container_setup/gitpod_workspace/workspacestop_and_restart.md
+ - container_setup/gitpod_workspace/live_share.md
+ - Local Setup:
+ - container_setup/local_setup/localsetup.md
+ - Tutorials:
+ - tutorials/building_r.md
+ - tutorials/running_r.md
+ - tutorials/contribution_workflow.md
+ - tutorials/update_source.md
+ - tutorials/patch_update.md
+ - tutorials/svn_help.md
+ - tutorials/multi_r_compilation.md
+ - Contributor Guide:
+ - contributor_guide/contributing_to_codebase.md
+ - contributor_guide/contributing_to_docs.md
+ - Resources: resources.md
+ - Troubleshooting: troubleshoot.md