From 31430f9d1885f8419041b92f199f674279a9d444 Mon Sep 17 00:00:00 2001 From: Neil Shephard Date: Fri, 11 Oct 2024 14:08:37 +0100 Subject: [PATCH] style(tutorials): Standardising sub-headings and layout As part of #191 the style of sub-headings for instructions in the `docs/tutorials/` section. + Level 2 markdown headings have been used, where numbering is required these have been included as the number followed by a period. + Bullet points have been converted to paragraphs. + alt text added to images. + titles added to code blocks. --- docs/tutorials/building_r.md | 104 ++++++++++++------------ docs/tutorials/contribution_workflow.md | 95 +++++++++++++--------- docs/tutorials/multi_r_compilation.md | 89 ++++++++++---------- docs/tutorials/patch_update.md | 15 ++-- docs/tutorials/running_r.md | 18 ++-- docs/tutorials/svn_help.md | 9 +- docs/tutorials/update_source.md | 45 +++++----- 7 files changed, 189 insertions(+), 186 deletions(-) diff --git a/docs/tutorials/building_r.md b/docs/tutorials/building_r.md index 7e6a59e1..e6b1c626 100644 --- a/docs/tutorials/building_r.md +++ b/docs/tutorials/building_r.md @@ -1,68 +1,70 @@ -**1) Environment variables** -- We have environment variables defining paths to directories for building R and - storing the source code. +This tutorial takes you through the process of building in the workspace container. + +## 1. Environment variable + +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. +- `PATCHDIR` defines the patch directory: `/workspaces/r-dev-env-/patches` - ![alt text](../assets/rdev6.png) +The environment variables are set in the codespace image and are available +when the codespace starts. -**2) svn checkout** +![Startup message of Containerised R Development Environment showing the environment variables](../assets/rdev6.png) -- 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: +## 2. svn checkout - ```bash - svn checkout https://svn.r-project.org/R/trunk/ $TOP_SRCDIR - ``` +R uses [Apache Subversion](https://subversion.apache.org/), an older version +control system than Git, to version control the code. + +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: + +```bash title="Checking out the main branch to $TOP_SRCDIR" +svn checkout https://svn.r-project.org/R/trunk/ $TOP_SRCDIR +``` -- Output : We get file structure something like this after checking out R source - code from R svn repository. +We get file structure something like this after checking out R source code from +R svn repository. - ![alt text](../assets/rdev8.png) +![Directory structure of the `main` branch after checkout](../assets/rdev8.png) -**3) Download recommended packages for R** +## 3. Download recommended packages for R 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: -```bash +```bash title="Synchronising the recommended packages" $TOP_SRCDIR/tools/rsync-recommended ``` -![alt text](../assets/rdev9.png) +![Synchronising the recommended packages](../assets/rdev9.png) -**4) Change to the build directory** +## 4. Change to the build director -- To keep the source directory clean, we change to a build directory to - configure and build R. +To keep the source directory clean, we change to a build directory to configure +and build R. -- First create the directory specified by the BUILDDIR environment variable. +Create and change to the directory specified by the BUILDDIR environment variable. -```bash +```bash title="Creating the $BUILDDIR and moving to it" mkdir -p $BUILDDIR -``` - -- Then we can change directory from root to the build directory. - -```bash cd $BUILDDIR ``` -**5) Configure the build** +## 5. Configure the build -- After we change directory, we must run the configure script from the source +After we change directory, we must run the configure script from the source directory. This step takes ~1 minute on the codespace. -```bash +```bash title="Configuring the build" $TOP_SRCDIR/configure --with-valgrind-instrumentation=1 - ``` !!! Note @@ -70,44 +72,39 @@ $TOP_SRCDIR/configure --with-valgrind-instrumentation=1 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. -- 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 configure command prepares for building R, creating files and folders inside +the `$BUILDDIR` directory. - ![alt text](../assets/rdev7.png) +![File structure after having configure the build](../assets/rdev7.png) -**6) Build R** +## 6. Build Having configured R, we run `make` to build R. This take 5-10 minutes on the codespace. -```bash +```bash title="Building R using make" make ``` -**7) Check R** +## 7. Check R Check that the build of R passes R's standard checks: -```bash +```bash title="Running the test suite using make check" make check ``` -This takes a couple of minutes in the codespace. The check will stop with a +This takes a couple of minutes in the codespace. The check will stop with an 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. -**8) Make R terminals use the built R** +## 8. Make R terminals use the built R 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` -```bash +```bash title="Checking which version of R is being used." which_r -``` - -```bash 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: @@ -122,9 +119,8 @@ built![^1] selected version is saved in the VSCode settings, so will be saved when you stop and restart the codespace. -**9) Make contributions** +## 9. Make contributions -- 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. +After having built the current development version of R, we can now make +changes to the source code and contribute to the project. The [R Contribution +Workflow](./contribution_workflow.md) tutorial goes through this process. diff --git a/docs/tutorials/contribution_workflow.md b/docs/tutorials/contribution_workflow.md index 44f85846..fbc0047a 100644 --- a/docs/tutorials/contribution_workflow.md +++ b/docs/tutorials/contribution_workflow.md @@ -1,80 +1,95 @@ -#### 1. Example Contribution Workflow using the R Dev Container +This tutorial takes you through the various steps of making contributions to the +R code base -- 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. Attach to the R workspace - ![alt text](../assets/rdev11.png) +To start working in R we need to first attach to a workspace session of R. To do +this click on `R:(not attach)` at the bottom right of the VSCode window. This +will open an R terminal for us. - ![alt text](../assets/rdev12.png) +Figure: VSCode before attaching to an R Workspace session -- We can now run R commands. We will use the `utils::askYesNo()` function as an - example +![VSCode before attaching to an R Workspace session](../assets/rdev11.png) - ![alt text](../assets/rdev19.png) +![VSCode after attaching to an R Workspace session](../assets/rdev12.png) -```R - > askYesNo("Is this a good example?") - Is this a good example? (Yes/no/cancel) Yes - [1] TRUE +We can now run R commands. We will use the `utils::askYesNo()` function as an +example + +```R title="Running the existing askYesNo() function." +> 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` and +we want to edit line 20 where the `prompts` option is set. -- 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 +You can redirect to that file using... ```bash code $TOP_SRCDIR/src/library/utils/R/askYesNo.R ``` -**> Before edit:** ![alt text](../assets/rdev20.png) +**Before edit:** -```R title="askYesNo.R" linenums="20" - prompts = getOption("askYesNo", gettext(c("Yes", "No", "Cancel"))), +![askYesNo.R before editing](../assets/rdev20.png) + +```R title="askYesNo.R before editing" linenums="20" +> prompts = getOption("askYesNo", gettext(c("Yes", "No", "Cancel"))), ``` -**> With edit (for example - change to whatever you like!):** +**With edit (for example - change to whatever you like!):** -![alt text](../assets/rdev21.png) +![askYesNo.R after editing](../assets/rdev21.png) -```R title="askYesNo.R" linenums="20" - prompts = getOption("askYesNo", gettext(c("Oh yeah!", "Don't think so", "Cancel"))), +```R title="askYesNo.R after editing" linenums="20" +> prompts = getOption("askYesNo", gettext(c("Oh yeah!", "Don't think so", "Cancel"))), ``` -#### 3. Rebuild R +## 3. Rebuild R + +We are now ready to re-build R with our changes. Since we have only modified the +utils package, rebuilding R will only re-build the utils package. -- 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. -- First we need to be inside $BUILDDIR. -- Quit R with `q()` or by closing the R terminal. -- In the bash terminal, change to the build directory: +Quit R with `q()` or by closing the R terminal and in the bash terminal change +directory th the build directory. This is stored in the environment variable +`$BUILDDIR` so we can... ```bash cd $BUILDDIR ``` -- Now run the `make` command to rebuild R with the changes you made in - step 2. This will be much faster than the full build! +Now run the `make` command to rebuild R with the changes you made in step 2. +This will be much faster than the full build because only the changes we made to +the utils package are rebuild. ```bash make ``` -![alt text](../assets/rdev22.png) +![Output rebuilding R using make](../assets/rdev22.png) + +It's a good idea to check the changes you have made have not broken anything. +R comes with a test suite and you can run that on your local changes by +running `make check` to run R's test suite against your local changes. You may +skip this step while you are iterating on a bug fix or other development, until +you are ready to [create a patch](./patch_update.md) but remember to run the +tests before creating a patch. -- 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, - until you are ready to [create a patch](./patch_update.md). +To use the re-built R, simply open a new R terminal. -- To use the re-built R, simply open a new R terminal. +## 4. Cross check and Re-running Code -#### 4. Cross check and Re-running Code +You can check the edit has worked as expected by in the re-built R by re-running +the example code: -- Check the edit has worked as expected by re-running the example code: ![alt -text](../assets/rdev23.png) +![Example showing the modified output of askYesNo()](../assets/rdev23.png) -```R +```R title="Example showing the modified output of askYesNo()" > 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/multi_r_compilation.md b/docs/tutorials/multi_r_compilation.md index f6d71261..06a5eb75 100644 --- a/docs/tutorials/multi_r_compilation.md +++ b/docs/tutorials/multi_r_compilation.md @@ -10,68 +10,65 @@ It can be helpful to work with multiple versions of R: You can build multiple R versions in the same Codespaces environment. -1. First choose a name for the R version. This will be used to identify the - version and to name the build/source directory. By default, we use the name - `r-devel` and the environment variables `BUILDDIR` and `TOP_SRCDIR` are set - to match. +## 1.Choose a name - For illustration, we will use `r-devel-raw`, which you might use to name a - version of R that you never modify. +First choose a name for the R version. This will be used to identify the +`r-devel` and the environment variables `$BUILDDIR` and `$TOP_SRCDIR` are set +to match. -2. You can set the `BUILDDIR` and `TOP_SRCDIR` environment variables to match - your chosen name using the `set_build_r` function: +For illustration, we will use `r-devel-raw`, which you might use to name a +version of R that you never modify. - - Open a terminal in the codespace. +## 2. Set environment variables - - Run the `set_build_r` function with your chosen name as the argument, e.g. +You can set the `$BUILDDIR` and `$TOP_SRCDIR` environment variables to match +your chosen name using the `set_build_r` function: - ```bash - set_build_r r-devel-raw - ``` +Open a terminal in the codespace and run the `set_build_r` function with your +chosen name as the argument. The new values of the environment variables will be +printed as confirmation, for example... - The new values of the environment variables will be printed as - confirmation: +```bash title="Updating $BUILDDIR and $TOP_SRCDIR" +set_build_r r-devel-raw +BUILDDIR is now set to /workspaces/r-dev-env/build/r-devel-raw +TOP_SRCDIR is now set to /workspaces/r-dev-env/svn/r-devel-raw +``` - ```bash - BUILDDIR is now set to /workspaces/r-dev-env/build/r-devel-raw - TOP_SRCDIR is now set to /workspaces/r-dev-env/svn/r-devel-raw - ``` +## 3. Synchronise builds -3. If you have an unmodified build of R-devel using the default name of - `r-devel`, you can simply copy the sources and the build to the new - directories with `rsync`: +If you have an unmodified build of R-devel using the default name of +directories with `rsync`: - ```bash - rsync -a "$(dirname "$BUILDDIR")/r-devel/"* $BUILDDIR - rsync -a "$(dirname "$TOP_SRCDIR")/r-devel/"* $TOP_SRCDIR - ``` +```bash title="Synchronising builds." +rsync -a "$(dirname "$BUILDDIR")/r-devel/"* $BUILDDIR +rsync -a "$(dirname "$TOP_SRCDIR")/r-devel/"* $TOP_SRCDIR +``` - Otherwise you can follow the steps in the [Building R](./building_r.md) - tutorial to checkout the R sources and build R using the new source and - build directories. +Otherwise you can follow the steps in the [Building R](./building_r.md) +tutorial to checkout the R sources and build R using the new source and +build directories. -4. Once you have a build of R under the new build directory, you will see your - chosen name in the choices when running the `which_r` script to select the - version of R to run in new terminals, e.g. +## 4. Check your build is available - ```bash - which_r - ``` +Once you have a build of R under the new build directory, you will see your +chosen name in the choices when running the `which_r` script to select the +version of R to run in new terminals, e.g. - ```bash - 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 - 3. r-devel-raw +```bash title="Possible versions of R that are available shown by which_r" +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 +3. r-devel-raw Enter the number corresponding to the selected version: - ``` - -!!! Note +``` - `BUILDDIR` and `TOP_SRCDIR` will be set to the defaults using the label `r-devel` - whenever a new bash terminal is opened, e.g. when the codespace is restarted. +!!! Note + `$BUILDDIR` and `$TOP_SRCDIR` will be set to the defaults using the label + `r-devel` whenever a new bash terminal is opened, e.g. when the codespace is + restarted. Whenever following instructions that use these variables to refer to the build and source directory, be sure they are pointing to the desired version! diff --git a/docs/tutorials/patch_update.md b/docs/tutorials/patch_update.md index 1a75b5c5..cd20c0cc 100644 --- a/docs/tutorials/patch_update.md +++ b/docs/tutorials/patch_update.md @@ -1,27 +1,26 @@ A patch file captures the local changes (additions and deletions) to the source code. It can be shared on [R's Bugzilla](https://bugs.r-project.org/) to propose -a change to R, e.g. a fix for a bug. +a change to R, e.g. a fix for a bug. This tutorial goes through the process of +creating a patch for sharing. -To make a patch - -1) Update your local copy of the source +## 1. Update your local copy of the source If you have not recently updated your local copy of the R Subversion repository, follow the instructions in [Updating the Source Code](./update_source.md) to do this first. -2) Create a patch file +## 2. Create a patch file Go to the source directory and use `svn diff` to create a patch. -```bash +```bash title="Creating a patch.diff using svn diff" cd $TOP_SRCDIR svn diff > $PATCHDIR/patch.diff ``` -The patch file will be saved in the directory specified by the PATCHDIR +The patch file will be saved in the directory specified by the `$PATCHDIR` environment variable that is defined when the codespace starts -```bash +```bash title="Checking the location of the new patch file" echo $PATCHDIR/patch.diff ``` diff --git a/docs/tutorials/running_r.md b/docs/tutorials/running_r.md index 0d31d242..39f94d29 100644 --- a/docs/tutorials/running_r.md +++ b/docs/tutorials/running_r.md @@ -1,5 +1,8 @@ +This tutorial takes you through starting R in the workspace container. -1) Create a file in VS Code ending with a .R extension. You can create new files +## 1. Create a new file + +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 @@ -7,14 +10,17 @@ in the terminal to create and open an R file code R/test.R ``` -![alt text](../assets/rdev4.png) +![Screen shot of VSCode running the Containerised R Development Environment.](../assets/rdev4.png) -2) You should see `R:(not attached)` in the Status Bar at the bottom of the +You should see `R:(not attached)` in the Status Bar at the bottom of the VSCode window. -![alt text](../assets/rdev11.png) +![Status bar of VSCode showing message that `R:(not attached)`.](../assets/rdev11.png) + +## 2. Launch R -3) Click on the `R:(not attached)` link to launch an R terminal. You can then +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`. -![alt text](../assets/rdev12.png) ![alt text](../assets/rdev5.png) +![Screen shot of R session running in the Terminal tab of VSCode.](../assets/rdev12.png) +![VSCode screen shot showing R terminal and plot in a separate tab.](../assets/rdev5.png) diff --git a/docs/tutorials/svn_help.md b/docs/tutorials/svn_help.md index 431768bc..58089ec4 100644 --- a/docs/tutorials/svn_help.md +++ b/docs/tutorials/svn_help.md @@ -2,7 +2,7 @@ You can check out a specific revision of the R sources with -```bash +```bash title="Checking out commit 1234" svn checkout -r 1234 https://svn.r-project.org/R/trunk/ $TOP_SRCDIR ``` @@ -20,12 +20,9 @@ checkmark) and use the commit message to search for the corresponding Subversion revision. For example, to search the last 10 revisions for the log message "More @apifun and such annotations" -```bash +```bash title="Searching the last 10 revisions for a log message" cd $TOP_SRCDIR svn log --limit 10 --search "More @apifun and such annotations" -``` - -```bash /workspaces/r-dev-env/svn/r-devel $ svn log --limit 10 --search "More @apifun and such annotations" ------------------------------------------------------------------------ r86726 | luke | 2024-06-12 18:00:19 +0000 (Wed, 12 Jun 2024) | 2 lines @@ -43,7 +40,7 @@ More @apifun and such annotations. If you have already attempted to build R, you can re-run the make with the version identified in your search as follows: -```bash +```bash title="Checking out a commit, building and running tests" svn checkout -r 86726 https://svn.r-project.org/R/trunk/ $TOP_SRCDIR cd $BUILDDIR make diff --git a/docs/tutorials/update_source.md b/docs/tutorials/update_source.md index b052c093..54e9bf52 100644 --- a/docs/tutorials/update_source.md +++ b/docs/tutorials/update_source.md @@ -3,56 +3,49 @@ 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. +If you have an R terminal open, quit R (`q()`) or close the terminal. -#### 2) Go to the source directory - -In a bash terminal, change to the source directory - -```bash -cd $TOP_SRCDIR -``` - -#### 3) Review local changes +## 2. Review local changes Use the Subversion diff command to review changes you have made to source code -```bash +```bash title="Reviewing local changes" +cd $TOP_SRCDIR svn diff ``` -#### 4) Revert changes (optional) +## 3. Revert changes (optional) If you no longer want to keep your local changes, you can revert them. -Revert the changes made in specific file +This can be done on a specific file -```bash +```bash title="Reverting changes to a specific file" svn revert src/library/utils/R/askYesNo.R ``` -Revert changes in a directory +...a whole directory... -```bash +```bash title="Reverting all changes in a specific directory" svn revert src/lib/utils ``` -Revert all local changes +...or all local changes -```bash +```bash title="Reverting all local changes" svn revert -R . ``` -#### 5) Rebuild and check with any local changes +## 4. Rebuild and check with any 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. -```bash +```bash title="Checking local changes pass tests" cd $BUILDDIR make make check @@ -62,25 +55,25 @@ 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 -```bash +```bash title="Changing directory" cd $TOP_SRCDIR ``` -#### 6) Update using svn +## 5. Update using svn Use the Subversion command `update` to update your local copy with the latest changes by the R Core Team. -```bash +```bash title="Updating" svn update ``` -#### 7) Rebuild and check with the updates +## 6. Rebuild and check with the 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 -```bash +```bash title="Running checks against the latest core changes" cd $BUILDDIR make make check