rstudio-conf-2022 / build-tidy-tools Goto Github PK

Build documentation
🎬 Run devtools::document()
MISSING COMMAND
ℹ Updating ussie documentation
ℹ Loading ussie
Writing NAMESPACE
Writing uss_make_matches.Rd
Warning message:
[matches.R:13] @examples requires a value

following Slack suggestions

One of the things initially discussed with @3mmaRand was that we would divide the course roughly as:

We could aim things so that the class would start the second day with a package that contains some small number of pure functions.

Assuming this, and seeing that each day has four sessions, here's a first pass for what I have in mind:

Function design

• pure functions vs. side effects (single most influential thing I have learned about functions)
• arrangement of parameters (data, descriptors, ..., details)
• type stability

Snapshot testing

• motivation: to test functions that produce side-effects
  • Emma will have covered testing of pure functions
• tools for writing error messages: rlang::abort()
• how to leave no footprints using {withr}

Tidy eval

• focus on functions that call tidyverse functions, using bare-name arguments:
  • designed for interactive use, i.e. just like dplyr::group_by()
  • data masking, tidy select, dynamic dots
• briefly mention other ways to use tidy eval:
  • functions that call tidyverse functions, using string-based arguments, e.g. for use with Shiny:
    • there's a correspondence for each of the techniques used for bare-named arguments.
  • implementing non-standard evaluation yourself:
    • mention the theory and tools exist, but that would be another class, which I would like to attend :)

as_function(), vctrs, and miscellany

• create purrr-style anonymous functions using rlang::as_function()
• implement S3 using vctrs
• implementing a format() method gets you a long way
• series of nuggets gleaned from reading Tidyverse Design Guide:
  • use this as "elastic" time should any of the previous material run long

Once this issue is settled, I'll open an issue to discuss each session in greater detail.

What do folks think?

Day 1

https://twitter.com/apreshill/status/1545752969064300544

switch dev workflow to mermaid

move: usethis::use_import_from("tibble", "tibble")
to Pkg Dependencies

Add a section on what to do if set up is a problem: we can use RStudio cloud, will need particpants to make an account and get an instructor account from Mine

my plan is to get a set of slides done, then to add in the references

By the end of the session, you will be able to:

• distinguish a pure function from a function that has or uses side effects.
• order and name your function's parameters
• recognize type-stable functions and their importance

Some principles to keep in mind:

• Principle of least surprise (astonishment): your design should help users learn how to use your function
  • A well-designed API can help folks learn (and remember) how to use your functions.
  • Tidyverse design guide has lots of well-earned advice.
• Postel's law, paraphrased: be lenient parsing input; be strict returning output

• 1
• 2
• 3
• 4

license is loading as home page presumably because license in the project directory with the _quarto.yml
Can we specify we is home page?
or
Can the build directory for the website be matierls rather than the project dir?

By the end of this session, you will be able to:

• accept a function an argument to a function using a formula (purrr-style)
• create an S3 class using {vctrs}
  • recognize that implementing a format() method gets you a long way
• appreciate a selection of nuggets gleaned from the Tidyverse Design Guide:
  • this will be "elastic" time should any of the previous material run long

my goodness, I'm glad I had the chance to stumble on tidy eval in "practice"

1100 - 1230

Learning Objectives
At the end of this section you will be able to:

to..
be..
added
Why? and definitions
exploring in console gets tedious
write unit tests instead - automates testing
improve interface, readability
what is a unit?
what is coverage
Workflow
use package started in Session 1
use function created in Session 1
use_test()
what happens? creates tests/testthat/ and test-xxxx.R where xxxx is the same name as the file with the function.
one test file per .R in R/
Most impt: expect_equal(obj, exp). Other: expect_true(), expect_type() and expect_length()
Set up keyborad shortcuts for testing workflow??
Report test coverage for a file Cmd+R `test_coverage_active_file()
Report test coverage for a package Shift+Cmd+R devtools::test_coverage()
Run a test file Cmd-T devtools::test_file()
Test driven development

By the end of this session, you will be able to:

• build functions that call tidyverse functions, using bare-name arguments:
  • designed for interactive use, i.e. just like dplyr::group_by()
  • understand tidy eval nomenclature: data masking, tidy select, dynamic dots
• recognize other ways to use tidy eval:
  • functions that call tidyverse functions, using string-based arguments, e.g. for use with Shiny:
    • recognize the correspondence for each of the techniques used for bare-name arguments.
  • implementation of non-standard evaluation:
    • understand that theory and tools exist.

Day 1

1530 -1700

Learning Objectives

At the end of this section you will be able to:

• to..
• be..
• added

README

Big picture goes in the README: usethis::use_readme_rmd()

• 2 -3 paragraph overview
• installations instructions
• usage example, with links to Vignettes
  Changes to the API: usethis::use_news_md() see the tidyverse style guide

Vignettes

• intro or specific use
• examples
• usethis::use_vignette("name of vignette")
  • change to DESCRIPTION
  • vignettes/ folder

pkgdown sites

• usethis::use_pkgdown()
• devtools::build_site()
• hosting
  • GitHub
  • let github build the page rather than building and hosting results. usethis::use_github_action("pkgdown")

given our shortlink 🎉, I'd like to make the materials as "close" as possible to the target of the link

exchange the word 'test' for 'experiment with' or similar to avoid confusion with unit testing

Chesapeake F

By the end of the session, you will be able to:

• write effective error messages
• manage the global state (leave no footprints) using {withr}
• test functions that use or cause side-effects
• use snapshot testing

this is needed for the scale to work in uss_plot_seasons_tiers()

I'll make a quick PR here; this will give @3mmaRand a chance to weigh in if this will be the right spot to make the change.

• #68
• add Kailey to roster
• #69

@3mmaRand, I'd be happy to make corresponding changes to day-1 session-1, if you like.

1100 - 1230

Learning Objectives

At the end of this section you will be able to:

• to..
• be..
• added

Why? and definitions

• exploring in console gets tedious
• write unit tests instead - automates testing
• improve interface, readability
• what is a unit?
• what is coverage

Workflow

• use package started in Session 1
• use function created in Session 1
• use_test()
  • what happens? creates tests/testthat/ and test-xxxx.R where xxxx is the same name as the file with the function.
• one test file per .R in R/
• Most impt: expect_equal(obj, exp). Other: expect_true(), expect_type() and expect_length()
• Set up keyborad shortcuts for testing workflow??
  • Report test coverage for a file Cmd+R `test_coverage_active_file()
  • Report test coverage for a package Shift+Cmd+R devtools::test_coverage()
  • Run a test file Cmd-T devtools::test_file()
• Test driven development

I rarely make bitly links, but I noticed that it seems like you need a paid account to generate custom links (I don't have one).

If we were to use a custom link, I was thinking:

btt22 - taken
btt-22 - still there

If need be, could RStudio generate a link?

ha!

day 1 went very well! I noted a few typos, so I'll put them all in a big PR

0900 - 1030

Welcome and introductions ~15 mins

• Schedule for the workshop
• Guidelines, CoC, stickies

Learning Objectives

At the end of this section you will be able to:

• find and explore their own package library/libraries
• describe the key components of a minimal package
• describe the different states a package can be in
• outline the development of a package using devtools
• create a simple version controlled package with a remote repo on GitHub
• use the package interactively with load_all()
• check package validity with check()

Packages in a nutshell

Get to know your R installation

Version, R.home(), .Library .libPaths()
From: CRAN, GitHub, Bioconductor

Developing a script vs developing a package

Explore a package

use our demo pkg??

Package states

• source
• bundled
• binary
• installed
• in-memory

The Whole game

Making a minimal version controlled package linked to a remote repository on GitHub using the devtools approach.
usethis::create_package

• new folder, restart, Build pane, .RProj
• infrastructure: DESCRIPTION, R/, NAMESPACE, .Rbuildignore .gitignore
  usethis::use_r()
• note the use_test() message
• add a function
  devtools::load_all()
• explore in console
• make a change, repeat
  devtools::check()
• errors, warnings, notes (perhaps our function should have an import which would then be listed in the warnings along with the lack of license)
  devtools::install()
  add roxygen skeleton and then devtools::document(), (maybe leave until session 3)
  ?function
  add a license (maybe leave until session 3)
  edit DESCRIPTION
• title, version, authors
  Use git
• git_sitrep()
• use_git()
• use_github()

This finally clicked for me when I rewatched Lionel Henry's rstudio::conf presentation: https://www.youtube.com/watch?v=SW_TUkPXSmA

The purpose of all_of() and any_of() is to disambiguate data-variables from environment-variables in tidy select:

library("dplyr")

cyl <- c("mpg", "wt")

mtcars |> select(cyl)

mtcars |> select(all_of(cyl))

We need to use it only when we are making a tidy-select specification using a variable and we want to ensure that the variable is not interpreted in the context of the data frame.

things that fit into RStudio pane do not fit into fullscreen

Learning Objectives

At the end of this section you will be able to:

• to..
• be..
• added

Different levels of documentation

• Metadata
• Package dependencies
• Object documentation
• Licensing (or might be in session 1)
• README
• Vignettes
• pkgdown sites

ref: The Grand Unified Theory of Documentation https://documentation.divio.com/

Metadata

• the DESCRIPTION file

• view others e.g., ggplot2

• Set up your .Rprofile usethis::edit_r_profile

Package dependencies

• recall the error from devtools::check()
• difference between Imports, Suggests and Depends
• usethis::use_package()
• view DESCRIPTION, NAMSPACE
• Run devtools::check() again.

Object documentation

• R comments --> Rd files (by roxygen2) --> HTML (by R)
• inerst roxygen skeleton
• roxygen comments in the .R files #' and @
  1. @param arg ---- describe the inputs
  2. @examples ---- show how the function works
  3. @seealso ---- point out related functions
  4. @returns ---- describe the outputs
  5. @param arg ---- is this a user visible function
• roxygen can include markdown formatting
• devtools::document() wrapper for roxygen2 function

1330 -1500 and 1530 -1700 (haven't decided where to split materials yet)

Learning Objectives

At the end of this section you will be able to:

• to..
• be..
• added

Different levels of documentation

• Metadata
• Package dependencies
• Object documentation
• Licensing (or might be in session 1)
• README
• Vignettes
• pkgdown sites

ref: The Grand Unified Theory of Documentation https://documentation.divio.com/

Metadata

• the DESCRIPTION file
• view others e.g., ggplot2

Licensing (or might be in session 1)

• recall the error from devtools::check()

• components

• usethis helpers

• view DESCRIPTION

• Set up your .Rprofile usethis::edit_r_profile

Package dependencies

• recall the error from devtools::check()
• difference between Imports, Suggests and Depends
• usethis::use_package()
• view DESCRIPTION, NAMSPACE
• Run devtools::check() again.

Object documentation

• R comments --> Rd files (by roxygen2) --> HTML (by R)
• inerst roxygen skeleton
• roxygen comments in the .R files #' and @
  1. @param arg ---- describe the inputs
  2. @examples ---- show how the function works
  3. @seealso ---- point out related functions
  4. @returns ---- describe the outputs
  5. @param arg ---- is this a user visible function
• roxygen can include markdown formatting
• devtools::document() wrapper for roxygen2 function

⬆️ session 3 ?
⬇️ session 4 ?

README

Big picture goes in the README: usethis::use_readme_rmd()

• 2 -3 paragraph overview
• installations instructions
• usage example, with links to Vignettes
  Changes to the API: usethis::use_news_md() see the tidyverse style guide

Vignettes

• intro or specific use
• examples
• usethis::use_vignette("name of vignette")
  • change to DESCRIPTION
  • vignettes/ folder

pkgdown sites

• usethis::use_pkgdown()
• devtools::build_site()
• hosting
  • GitHub
  • let github build the page rather than building and hosting results. usethis::use_github_action("pkgdown")