Add the path argument to gtsave()

[rich-iannone]

The addition of a path argument to gtsave() aligns this function more closely to the ggplot2::ggsave() function. If a path is provided, then it will be combined with the filename argument. Path expansion still occurs (so the ~ can be safely used). Here is an example usage with the changes in this PR.

library(gt)
library(tidyverse)

# Use `gtcars` to create a gt table; add
# a stubhead label to describe what is
# in the stub
tab_1 <-
  gtcars %>%
  dplyr::select(model, year, hp, trq) %>%
  dplyr::slice(1:5) %>%
  gt(rowname_col = "model") %>%
  tab_stubhead_label(label = "car")

# Save the HTML table as a PDF file; we
# can optionally add a separate `path`
tab_1 %>% gtsave("tab_1.pdf", path = "~")

This PR also improves the documentation for gtsave(), providing information on what options can be used in the ... (with links to the underlying functions for more details).

Fixes #284.

[gregrs-uk]

Many thanks for this. It would be handy if you could also supply a relative path to the path argument of gtsave() as below:

library(gt)

# this saves in home directory (at least on a Mac) using an absolute path
gtcars %>%
  gt() %>%
  gtsave("test.html", path = "~")

# uses relative path
dir.create("out")

# this complains because the absolute path /out doesn't exist
gtcars %>%
  gt() %>%
  gtsave("test.html", path = "out")
#> Warning in base::file(file, open = "w+b"): cannot open file 'out/
#> test.html': No such file or directory
#> Error in base::file(file, open = "w+b"): cannot open the connection

# this works but is a bit fiddly
gtcars %>%
  gt() %>%
  gtsave("test.html", path = file.path(getwd(), "out"))

^{Created on 2020-01-02 by the reprex package (v0.3.0)}

Session info

devtools::session_info()
#> ─ Session info ──────────────────────────────────────────────────────────
#>  setting  value                       
#>  version  R version 3.6.1 (2019-07-05)
#>  os       macOS Sierra 10.12.6        
#>  system   x86_64, darwin15.6.0        
#>  ui       X11                         
#>  language (EN)                        
#>  collate  en_GB.UTF-8                 
#>  ctype    en_GB.UTF-8                 
#>  tz       Europe/London               
#>  date     2020-01-02                  
#> 
#> ─ Packages ──────────────────────────────────────────────────────────────
#>  package     * version date       lib source                     
#>  assertthat    0.2.1   2019-03-21 [1] CRAN (R 3.6.0)             
#>  backports     1.1.5   2019-10-02 [1] CRAN (R 3.6.0)             
#>  callr         3.3.2   2019-09-22 [1] CRAN (R 3.6.1)             
#>  checkmate     1.9.4   2019-07-04 [1] CRAN (R 3.6.0)             
#>  cli           2.0.0   2019-12-09 [1] CRAN (R 3.6.0)             
#>  colorspace    1.4-1   2019-03-18 [1] CRAN (R 3.6.0)             
#>  crayon        1.3.4   2017-09-16 [1] CRAN (R 3.6.0)             
#>  desc          1.2.0   2018-05-01 [1] CRAN (R 3.6.0)             
#>  devtools      2.2.0   2019-09-07 [1] CRAN (R 3.6.0)             
#>  digest        0.6.23  2019-11-23 [1] CRAN (R 3.6.1)             
#>  dplyr         0.8.3   2019-07-04 [1] CRAN (R 3.6.0)             
#>  DT            0.9     2019-09-17 [1] CRAN (R 3.6.0)             
#>  ellipsis      0.3.0   2019-09-20 [1] CRAN (R 3.6.0)             
#>  evaluate      0.14    2019-05-28 [1] CRAN (R 3.6.0)             
#>  fansi         0.4.0   2018-10-05 [1] CRAN (R 3.6.0)             
#>  fs            1.3.1   2019-05-06 [1] CRAN (R 3.6.0)             
#>  ggplot2       3.2.1   2019-08-10 [1] CRAN (R 3.6.0)             
#>  glue          1.3.1   2019-03-12 [1] CRAN (R 3.6.0)             
#>  gt          * 0.1.0   2020-01-02 [1] Github (rstudio/gt@990d348)
#>  gtable        0.3.0   2019-03-25 [1] CRAN (R 3.6.0)             
#>  highr         0.8     2019-03-20 [1] CRAN (R 3.6.0)             
#>  htmltools     0.4.0   2019-10-04 [1] CRAN (R 3.6.0)             
#>  htmlwidgets   1.3     2018-09-30 [1] CRAN (R 3.6.0)             
#>  knitr         1.25    2019-09-18 [1] CRAN (R 3.6.0)             
#>  lazyeval      0.2.2   2019-03-15 [1] CRAN (R 3.6.0)             
#>  lifecycle     0.1.0   2019-08-01 [1] CRAN (R 3.6.0)             
#>  magrittr      1.5     2014-11-22 [1] CRAN (R 3.6.0)             
#>  memoise       1.1.0   2017-04-21 [1] CRAN (R 3.6.0)             
#>  munsell       0.5.0   2018-06-12 [1] CRAN (R 3.6.0)             
#>  pillar        1.4.3   2019-12-20 [1] CRAN (R 3.6.0)             
#>  pkgbuild      1.0.5   2019-08-26 [1] CRAN (R 3.6.0)             
#>  pkgconfig     2.0.3   2019-09-22 [1] CRAN (R 3.6.1)             
#>  pkgload       1.0.2   2018-10-29 [1] CRAN (R 3.6.0)             
#>  prettyunits   1.0.2   2015-07-13 [1] CRAN (R 3.6.0)             
#>  processx      3.4.1   2019-07-18 [1] CRAN (R 3.6.0)             
#>  ps            1.3.0   2018-12-21 [1] CRAN (R 3.6.0)             
#>  purrr         0.3.3   2019-10-18 [1] CRAN (R 3.6.0)             
#>  R6            2.4.1   2019-11-12 [1] CRAN (R 3.6.0)             
#>  Rcpp          1.0.3   2019-11-08 [1] CRAN (R 3.6.0)             
#>  remotes       2.1.0   2019-06-24 [1] CRAN (R 3.6.0)             
#>  rlang         0.4.2   2019-11-23 [1] CRAN (R 3.6.1)             
#>  rmarkdown     1.15    2019-08-21 [1] CRAN (R 3.6.0)             
#>  rprojroot     1.3-2   2018-01-03 [1] CRAN (R 3.6.0)             
#>  sass          0.1.2.1 2019-08-08 [1] CRAN (R 3.6.0)             
#>  scales        1.1.0   2019-11-18 [1] CRAN (R 3.6.0)             
#>  sessioninfo   1.1.1   2018-11-05 [1] CRAN (R 3.6.0)             
#>  stringi       1.4.3   2019-03-12 [1] CRAN (R 3.6.0)             
#>  stringr       1.4.0   2019-02-10 [1] CRAN (R 3.6.0)             
#>  testthat      2.2.1   2019-07-25 [1] CRAN (R 3.6.0)             
#>  tibble        2.1.3   2019-06-06 [1] CRAN (R 3.6.0)             
#>  tidyselect    0.2.5   2018-10-11 [1] CRAN (R 3.6.0)             
#>  usethis       1.5.1   2019-07-04 [1] CRAN (R 3.6.0)             
#>  withr         2.1.2   2018-03-15 [1] CRAN (R 3.6.0)             
#>  xfun          0.9     2019-08-21 [1] CRAN (R 3.6.0)             
#>  yaml          2.2.0   2018-07-25 [1] CRAN (R 3.6.0)             
#> 
#> [1] /Library/Frameworks/R.framework/Versions/3.6/Resources/library