tl;dr
I made a couple of packages that contain RStudio Addins: {quartostamp} inserts little divs and classes into your Quarto documents, while {snorkel} inserts Rd tags into your {roxygen2} function documentation.
Al Addin
RStudio Addins let you access R functions interactively at the click of a button (or with a keyboard shortcut, or via the RStudio command palette). I particularly like them for easy sharing of insertable pre-written code.
See Dean Attali’s {addinslist} package for examples or the {shrtcts} package by Garrick Aden-Buie for an alternative approach to ‘make anything an RStudio shortcut’.
On my part:
- I wrote about the little {backtick} Addin package that inserts backticks (`) and backtick constructions1
- I wrote about the {r2eng} package, which has an Addin that lets you highlight some R code and then speak that expression out loud in English
- I wrote about the {blogsnip} Addin package that can manipulate code used to write this blog
- the {a11ytables} package has an Addin to insert code skeletons for creating publishable best-practice spreadsheets
RStudio Addins are kinda straightforward to put into in an R package. Put your functions in R/
as usual, then write an inst/rstudio/addins.dcf
file to declare your functions (e.g. see {backtick}’s .dcf). Learn more from Sharon Machlis and Jozef Hajnala.
The user can then select the functions from the ‘Addins’ dropdown in the RStudio IDE.
Of late I’ve written two packages—{quartostamp} and {snorkel}—that contain RStudio Addins to help me write code structures that I struggle to remember when writing Quarto documents and function documentation.
Others seem to have found these useful, so I thought I’d ‘officially’ signal that they exist.
{quartostamp}
Quarto—‘new R Markdown’—is all the rage right now, having been officially launched at the recent rstudio::conf(2022) conference. Folks are going bonkers for tools and techniques to learn and implement it. A good place to begin is the Awesome Quarto List by Mickaël Canouil.
Featured there is {quartostamp}, a little R package I made that contains an RStudio Addin to insert into your Quarto doc a number of useful divs and classes. As the README puts it:
Why ‘quartostamp’? You could physically stamp some pre-prepared type into a literal quarto document; you can digitally stamp some pre-written elements into your qmd file.
![Hex logo for the quartostamp package. Blue outline. Red 'flower stamp' emoji in the centre. It says 'quartostamp' in the top left and the URL matt-dray.github.io/quartostamp in the lower right, both in red text.](/post/2022-08-10-more-addins_files/logo.png)
{quartostamp}’s hex logo.
You can install it from GitHub like:
# install.packages("remotes") # if not yet installed
remotes::install_github("matt-dray/quartostamp")
As an example, did you forget how to insert speaker notes into a presentation? Go to Addins > Insert Speaker Notes and this will be inserted to your doc:
::: {.notes}
Speaker notes go here.
:::
That’s a straightforward one; a two-column layout is more complex. Go to Addins > Insert Column Layout and you get this:
:::: {.columns}
::: {.column width='40%'}
Left column
:::
::: {.column width='60%'}
Right column
:::
::::
These elements are basically lifted from the docs, so big shoutout to the authors JJ Allaire, Charles Teague, Carlos Scheidegger, Yihui Xie and Christophe Dervieux.
Go to the package website to see the current list of functions available in the Addin. Click them to learn more, including a preview of the actual text that will be inserted into your document.
I think the limits of the package are the content that you would insert in the body of your Quarto doc, or to places like Revealjs slide headings. In other words, not Quarto YAML nor chunk options. These are autocompleted in RStudio, or otherwise dealt with already elsewhere.
Do submit your ideas for {quartodown} as issues or pull requests in the GitHub repo.
{snorkel}
The {snorkel} package2 is another solution to storing syntax outside of my own brain. In this case, it helps out with formatting text in {roxygen2} function documentation.3
The reason for the name should be obvious.4 As the package README puts it:
You put a snorkel in your mouth to help you breathe oxygen; you put a {snorkel} in your addins to help you write with {roxygen2}.
Yes, this is package-name-driven development; I thought of the name before writing anything.
Install from GitHub like:
# install.packages("remotes") # if not yet installed
remotes::install_github("matt-dray/snorkel")
So, how would you embolden a word in your function documentation? Highlight the word and then go to Addins > Format Bold and you get:
#' I am a \strong{bold} boy.
Here’s something more complex: how can you link to a function in an external package? Write the package function in the form package::function
, highlight it and then select Addins > Link To Function (Another Package) and you get:
#' When the crowd say 'Bo \code{\link[dplyr]{select}}a'.
The functions in the Addin insert code mentioned in the {roxygen2} docs, so big shoutout to the authors Hadley Wickham, Peter Danenberg, Gabor Csárdi, Manuel Eugster and RStudio.
The package website has a list of the functions available in the Addin,5 which you can click to see previews of what each one will insert.
For now I think the functions in the package should focus just on the Rd tags that format the documentation, rather than the {roxygen2} tags (like @description
, @params
, etc). The latter are already autocompleted in RStudio, so I feel like there’s less need. Similarly, the package doesn’t include functions to insert Markdown into function documentation, but perhaps it could be expanded in future.
New functionality is always welcome; please raise an issue or pull request in the GitHub repo.
Addin your suggestions
I made these primarily for myself; I’m really bad at remembering syntax. I always need ‘a brain outside my brain’. Maybe they’ll be useful for you too.
Perhaps you can help out by expanding the list of functions in these packages. Please add any suggestions or features in an issue or pull request in either GitHub repo.
So, don’t be a cad, it would be maddenin’ and saddenin’ if you hadn’t added in your Addin ideas, so be a rad chad and add your addins in the Addins.
Session info
## ─ Session info ───────────────────────────────────────────────────────────────
## setting value
## version R version 4.2.0 (2022-04-22)
## os macOS Big Sur/Monterey 10.16
## system x86_64, darwin17.0
## ui X11
## language (EN)
## collate en_GB.UTF-8
## ctype en_GB.UTF-8
## tz Europe/London
## date 2022-08-14
## pandoc 2.18 @ /Applications/RStudio.app/Contents/MacOS/quarto/bin/tools/ (via rmarkdown)
##
## ─ Packages ───────────────────────────────────────────────────────────────────
## package * version date (UTC) lib source
## blogdown 1.9 2022-03-28 [1] CRAN (R 4.2.0)
## bookdown 0.26 2022-04-15 [1] CRAN (R 4.2.0)
## bslib 0.3.1 2021-10-06 [1] CRAN (R 4.2.0)
## cli 3.3.0 2022-04-25 [1] CRAN (R 4.2.0)
## digest 0.6.29 2021-12-01 [1] CRAN (R 4.2.0)
## evaluate 0.15 2022-02-18 [1] CRAN (R 4.2.0)
## fastmap 1.1.0 2021-01-25 [1] CRAN (R 4.2.0)
## htmltools 0.5.2 2021-08-25 [1] CRAN (R 4.2.0)
## jquerylib 0.1.4 2021-04-26 [1] CRAN (R 4.2.0)
## jsonlite 1.8.0 2022-02-22 [1] CRAN (R 4.2.0)
## knitr 1.39 2022-04-26 [1] CRAN (R 4.2.0)
## magrittr 2.0.3 2022-03-30 [1] CRAN (R 4.2.0)
## R6 2.5.1 2021-08-19 [1] CRAN (R 4.2.0)
## rlang 1.0.2 2022-03-04 [1] CRAN (R 4.2.0)
## rmarkdown 2.14 2022-04-25 [1] CRAN (R 4.2.0)
## rstudioapi 0.13 2020-11-12 [1] CRAN (R 4.2.0)
## sass 0.4.1 2022-03-23 [1] CRAN (R 4.2.0)
## sessioninfo 1.2.2 2021-12-06 [1] CRAN (R 4.2.0)
## stringi 1.7.6 2021-11-29 [1] CRAN (R 4.2.0)
## stringr 1.4.0 2019-02-10 [1] CRAN (R 4.2.0)
## xfun 0.30 2022-03-02 [1] CRAN (R 4.2.0)
## yaml 2.3.5 2022-02-21 [1] CRAN (R 4.2.0)
##
## [1] /Library/Frameworks/R.framework/Versions/4.2/Resources/library
##
## ──────────────────────────────────────────────────────────────────────────────
Yes, there are use cases for this! For example, Italian keyboards don’t have a backtick?!↩︎
I sort-of announced this before in the {backtick} post, but then John Mackintosh signal-boosted it on Twitter and folks seemed interested, so here we are.↩︎
But note that you can write documentation with Markdown! I may expand the package to cover this in future.↩︎
Although I still like ‘{aqualung}’ as a package name.↩︎
Yes, there is an Easter-egg function in the package for your wellbeing.↩︎