Closes #69 code sections (#70)

* Initial setup of code sections article

* #69 Code sections article completed

* #69 chore: spellcheck

* #69 chore: spellcheck

* Update posts/2023-07-14_code_sections/code_sections.qmd

Co-authored-by: Kangjie Zhang <47867131+kaz462@users.noreply.github.com>

* Update posts/2023-07-14_code_sections/code_sections.qmd

Co-authored-by: Kangjie Zhang <47867131+kaz462@users.noreply.github.com>

* Update posts/2023-07-14_code_sections/code_sections.qmd

Co-authored-by: Kangjie Zhang <47867131+kaz462@users.noreply.github.com>

* Update code_sections.qmd

* fix: #69 re-size image. add appendix. broken links

* #69 replace admiral hex with rstudio hex

* #69 added info about outline view, added mac shortcuts, improved screenshots

* #69 chore: spelling

---------

Co-authored-by: Kangjie Zhang <47867131+kaz462@users.noreply.github.com>
Co-authored-by: Ben Straub <ben.x.straub@gsk.com>

inst/WORDLIST.txt

@@ -104,9 +104,11 @@ ADPCYMG
 AVAL
 bdat
 BDS
+Cmd
 exprs
 frac
 Kangjie
+Mac
 NUMCYC
 param
 PARAM
@@ -147,6 +149,7 @@ ADLBHY
 ADSL
 ADTTE
 ADVS
+adae
 aes
 bb
 ben
@@ -165,6 +168,7 @@ ggplot
 ggtitle
 gsk
 GSK
+ide
 introR
 Jagadish
 jagadishkatam
@@ -182,6 +186,7 @@ readxl
 registrationData
 renderUI
 roche
+RStudio
 rStudio
 sadchla
 Sadchla
@@ -197,6 +202,7 @@ TatianaPXL
 teamspoRt
 textInput
 thomasneitmann
+traversable
 UI
 useNA
 ViiV

posts/2023-07-10_blanks_and_nas/appendix.R

@@ -23,7 +23,7 @@ insert_source <- function(repo_spec, name,
     branch,
     collection,
     name,
-    "index.qmd",
+    "blanks_and_na.qmd",
     sep = "/"
   )
   return(markdown_link(text, path))

posts/2023-07-14_code_sections/appendix.R

@@ -0,0 +1,78 @@
+# markdown helpers --------------------------------------------------------
+
+markdown_appendix <- function(name, content) {
+  paste(paste("##", name, "{.appendix}"), " ", content, sep = "\n")
+}
+markdown_link <- function(text, path) {
+  paste0("[", text, "](", path, ")")
+}
+
+
+
+# worker functions --------------------------------------------------------
+
+insert_source <- function(repo_spec, name,
+                          collection = "posts",
+                          branch = "main",
+                          host = "https://github.com",
+                          text = "source code") {
+  path <- paste(
+    host,
+    repo_spec,
+    "tree",
+    branch,
+    collection,
+    name,
+    "code_sections.qmd",
+    sep = "/"
+  )
+  return(markdown_link(text, path))
+}
+
+insert_timestamp <- function(tzone = Sys.timezone()) {
+  time <- lubridate::now(tzone = tzone)
+  stamp <- as.character(time, tz = tzone, usetz = TRUE)
+  return(stamp)
+}
+
+insert_lockfile <- function(repo_spec, name,
+                            collection = "posts",
+                            branch = "main",
+                            host = "https://github.com",
+                            text = "R environment") {
+  path <- paste(
+    host,
+    repo_spec,
+    "tree",
+    branch,
+    collection,
+    name,
+    "renv.lock",
+    sep = "/"
+  )
+  return(markdown_link(text, path))
+}
+
+
+
+# top level function ------------------------------------------------------
+
+insert_appendix <- function(repo_spec, name, collection = "posts") {
+  appendices <- paste(
+    markdown_appendix(
+      name = "Last updated",
+      content = insert_timestamp()
+    ),
+    " ",
+    markdown_appendix(
+      name = "Details",
+      content = paste(
+        insert_source(repo_spec, name, collection),
+        insert_lockfile(repo_spec, name, collection),
+        sep = ", "
+      )
+    ),
+    sep = "\n"
+  )
+  knitr::asis_output(appendices)
+}

posts/2023-07-14_code_sections/code_sections.qmd

@@ -0,0 +1,101 @@
+---
+title: "How to use Code Sections"
+author:
+  - name: Edoardo Mancini
+description: ""
+date: "2023-07-14"
+# please do not use any non-default categories.
+# You can find the default categories in the repository README.md
+categories: [ADaMs, Tips and Tricks]
+# feel free to change the image
+image: "rstudio-hex.PNG"
+
+---
+
+<!--------------- typical setup ----------------->
+
+```{r setup, include=FALSE}
+long_slug <- "2023-07-14_code_sections"
+# renv::use(lockfile = "renv.lock")
+```
+
+<!--------------- post begins here ----------------->
+
+## Introduction
+
+The [`admiral`](https://pharmaverse.github.io/admiral/cran-release/) package embraces a modular style of programming, where blocks of code are pieced together in sequence to create an ADaM dataset. However, with the well-documented advantages of the modular approach comes the recognition that scripts will on average be longer. As such, astute programmers working in RStudio are constantly on the lookout for quick ways to effectively navigate their scripts. Enter **code sections**!
+
+## So, what are code sections and why are they useful?
+
+[Code Sections](https://docs.posit.co/ide/user/ide/guide/code/code-sections.html) are separators for long R scripts or functions in RStudio. They can be set up by inserting a comment line followed by four or more dashes in between portions of code, like so:
+
+```{r, message = FALSE}
+# First code section ----
+
+a <- 1
+
+# Second code section ----
+
+b <- 2
+
+# Third code section ----
+
+c <- 3
+```
+RStudio then recognizes the code sections automatically, and enables you to:
+
+* Collapse and expand them using the arrow displayed next to the line number, or with the handy shortcuts `Alt+L`/`Shift+Alt+L` on Windows or `Cmd+Option+L`/`Cmd+Shift+Option+L` on Mac.
+* Travel in between them using the navigator at the bottom of the code pane, or by pressing `Shift+Alt+J` on Windows or `Cmd+Shift+Option+J` on Mac.
+* View an outline of the file using the "Outline" button at the top right of the pane and/or the orange hashtag "Section Navigator" button at the bottom left of the pane.
+
+```{r, fig.align = 'center', out.width = "100%", fig.cap = "Collapsed sections, outline view and the section navigator for the example above.", echo=FALSE}
+knitr::include_graphics("section_navigator.png")
+```
+
+It is also possible to create subsections by using two hashtags at the start of a comment line:
+
+```{r, message = FALSE}
+# First code section ----
+a <- 1
+
+## A code subsection ----
+b <- 2
+
+# Second code section ----
+c <- 3
+```
+
+```{r, fig.align = 'center', out.width = "45%", fig.cap = "Code subsections for the example above.", echo=FALSE}
+knitr::include_graphics("subsections.png")
+```
+
+For a complete list of Code Sections shortcuts, and for further information, see [here](https://docs.posit.co/ide/user/ide/guide/code/code-sections.html#menu-commands-and-shortcuts).
+
+# Code Sections on `admiral`
+
+Within the [`admiral`](https://pharmaverse.github.io/admiral/cran-release/) package, heavy use of code sections is made in scripts such as our template ADaM programs. This ensures that they are more traversable and also encourages good commenting practices throughout the program. Here is an example using the ADAE template program:
+
+```{r, eval = FALSE, message = FALSE}
+library(admiral)
+use_ad_template("ADAE")
+```
+
+Once the user saves this template program and opens it in their local file system, a 100+ line file instantly becomes more tractable due to the code sections that have been inserted.
+
+```{r, fig.align = 'center', out.width = "45%", fig.cap = "A screenshot of the code sections in the ADAE template script", echo=FALSE}
+knitr::include_graphics("adae_code_sections.png")
+```
+
+## Conclusion
+Code sections are an easy way to navigate long scripts and foster good commenting practices. They are used extensively in the [`admiral`](https://pharmaverse.github.io/admiral/cran-release/) package, but there is no reason that you cannot start using them yourself in your day-to-day R programming!
+
+<!--------------- appendices go here ----------------->
+
+```{r, echo=FALSE}
+source("appendix.R")
+insert_appendix(
+  repo_spec = "pharmaverse/blog",
+  name = long_slug
+)
+```
+