From d0f5c325765d6d7bd2d8593b1c087e956ceb9779 Mon Sep 17 00:00:00 2001
From: michaelm <michaelm@metrumrg.com>
Date: Wed, 26 Jun 2024 12:08:09 -0400
Subject: [PATCH] Add diff tools vignette

---
 vignettes/diff-tools.Rmd | 155 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 155 insertions(+)
 create mode 100644 vignettes/diff-tools.Rmd

diff --git a/vignettes/diff-tools.Rmd b/vignettes/diff-tools.Rmd
new file mode 100644
index 0000000..5bff089
--- /dev/null
+++ b/vignettes/diff-tools.Rmd
@@ -0,0 +1,155 @@
+---
+title: "Diff Tools"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{diff-tools}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+This vignette demonstrates using a variety of `diff-` functions to assist with
+QC efforts. All functions provide a visual difference of modifications to scripts.
+The functions covered below include:
+
+- `diffQced()` shows modifications to a script since it was last QCed.
+- `diffPreviousRevisions()` shows modifications between versions of the same script.
+- `diffFiles()` shows modifications between two scripts.
+
+# Load libraries
+
+```{r, message=FALSE}
+library(review)
+```
+
+# Setup
+
+For the purposes of this vignette, a demo SVN repository and files were created
+using the `demoRepo()` function. The files in this repository are versioned 
+and have past QC history.
+
+```{r}
+repo <- demoRepo("examp-123")
+```
+
+# diffQced
+
+`diffQced()` generates a visual diff in the Viewer pane in R studio. 
+All deleted, added and modified lines of code are shown in the diff. 
+
+`diffQced()` uses the QC log to identify the revision number when the last QC 
+was completed. The difference is then generated using the version of the file at 
+that revision number versus the current file.
+
+For this example, we will look at the modifications made to `script/data-assembly.R`
+since its last QC.
+
+```{r eval=FALSE}
+diffQced("script/data-assembly.R")
+```
+
+```{r echo=FALSE, message=FALSE, results='asis'}
+curdir <- getwd()
+on.exit(setwd(curdir))
+setwd(repo)
+svnExport("script/data-assembly.R", 1)
+
+diffobj::diffFile(
+        "data-assembly-1.R",
+        "script/data-assembly.R",
+        color.mode = "rgb",
+        ignore.white.space = FALSE,
+        mode = "sidebyside",
+        tar.banner="Revision 1",
+        cur.banner="Local",
+        format = "html",
+        style = list(html.output = "diff.w.style"),
+        interactive = F
+      )
+```
+
+# diffPreviousRevisions
+
+`diffPreviousRevisions()` generates a similar visual, except the versions 
+of the scripts being compared can be explicitly defined. 
+
+For any script, a previous and current revision number can be set to decide
+the versions being used. If a current revision number is not provided, the 
+default will be set to the most recent version of the script.
+
+For this example, we can use the `script/pk/load-spec.R` script. We can view
+the history of this file with `svnLog()`.
+
+```{r eval=FALSE}
+svnLog("script/pk/load-spec.R")
+```
+
+```{r echo=FALSE}
+curdir <- getwd()
+on.exit(setwd(curdir))
+setwd(repo)
+svnLog("script/pk/load-spec.R")
+```
+
+Now using `diffPreviousRevisions()`, we can look at the differences between 
+the file at revisions 1 and 4.
+
+```{r eval=FALSE}
+diffPreviousRevisions(
+    .file = "script/pk/load-spec.R",
+    .current_revision = 4,
+    .previous_revision = 1)
+```
+
+```{r echo=FALSE, message=FALSE, results='asis'}
+curdir <- getwd()
+on.exit(setwd(curdir))
+setwd(repo)
+svnExport("script/pk/load-spec.R", 1)
+
+diffobj::diffFile(
+        "load-spec-1.R",
+        "script/pk/load-spec.R",
+        color.mode = "rgb",
+        ignore.white.space = FALSE,
+        mode = "sidebyside",
+        tar.banner="Revision 1",
+        cur.banner="Local",
+        format = "html",
+        style = list(html.output = "diff.w.style"),
+        interactive = F
+      )
+```
+
+# diffFiles
+
+`diffFiles()` generates a visual diff between two files. The first file 
+provided will be treated as the past version when generating the visual diff.
+
+For this example, we can use the `script/combine-da.R` and 
+`script/data-assembly.R` scripts.
+
+```{r eval=FALSE}
+diffFiles(
+  .file_1 = "script/combine-da.R", 
+  .file_2 = "script/data-assembly.R"
+)
+```
+
+```{r echo=FALSE, message=FALSE, results='asis'}
+curdir <- getwd()
+on.exit(setwd(curdir))
+setwd(repo)
+
+diffobj::diffFile(
+        "script/combine-da.R",
+        "script/data-assembly.R",
+        color.mode = "rgb",
+        ignore.white.space = FALSE,
+        mode = "sidebyside",
+        tar.banner="Revision 1",
+        cur.banner="Local",
+        format = "html",
+        style = list(html.output = "diff.w.style"),
+        interactive = F
+      )
+```
\ No newline at end of file