Merge pull request #416 from cmu-delphi/ds/vignettes

doc: update sliding vignette

Author: dshemetov

DEVELOPMENT.md

@@ -1,10 +1,8 @@
 ## Setting up the development environment
 
 ```r
-install.packages(c('devtools', 'pkgdown', 'styler', 'lintr')) # install dev dependencies
-devtools::install_deps(dependencies = TRUE) # install package dependencies
-devtools::document() # generate package meta data and man files
-devtools::build() # build package
+install.packages(c('devtools', 'pkgdown', 'styler', 'lintr', 'pak')) # install dev dependencies
+pak::pkg_install(".") # install package and dependencies
 ```
 
 ## Validating the package
@@ -13,35 +11,71 @@ devtools::build() # build package
 styler::style_pkg() # format code
 lintr::lint_package() # lint code
 
+devtools::check() # run R CMD check, which runs everything below
+devtools::document() # generate package meta data and man files
 devtools::test() # test package
-devtools::check() # check package for errors
+devtools::build_vignettes() # build vignettes only
+devtools::run_examples() # run doc examples
+devtools::check(vignettes = FALSE) # check package without vignettes
 ```
 
 ## Developing the documentation site
 
-The [documentation site](https://cmu-delphi.github.io/epipredict/) is built off of the `main` branch. The `dev` version of the site is available at https://cmu-delphi.github.io/epipredict/dev.
-
-The documentation site can be previewed locally by running in R
-
-```r
-pkgdown::build_site(preview=TRUE)
-```
+Our CI builds two versions of the documentation:
 
-The `main` version is available at `file:///<local path>/epidatr/epipredict/index.html` and `dev` at `file:///<local path>/epipredict/docs/dev/index.html`.
+- https://cmu-delphi.github.io/epipredict/ from the `main` branch and
+- https://cmu-delphi.github.io/epipredict/dev from the `dev` branch.
 
-You can also build the docs manually and launch the site with python. From the terminal, this looks like
+Commands for developing the documentation site:
 
-```bash
+```sh
+# Basic build and preview
 R -e 'pkgdown::clean_site()'
 R -e 'devtools::document()'
 R -e 'pkgdown::build_site()'
-python -m http.server -d docs
 ```
 
+If you work without R Studio and want to iterate on documentation, you might
+find [this
+script](https://gist.github.com/gadenbuie/d22e149e65591b91419e41ea5b2e0621)
+helpful.
+
 ## Versioning
 
 Please follow the guidelines in the [PR template document](.github/pull_request_template.md).
 
-## Release process
+## Planned CRAN release process
+
+Open a release issue and then copy and follow this checklist in the issue (modified from the checklist generated by `usethis::use_release_issue(version = "1.0.2")`):
+
+- [ ] `git pull` on `dev` branch.
+- [ ] Make sure all changes are committed and pushed.
+- [ ] Check [current CRAN check results](https://cran.rstudio.org/web/checks/check_results_epipredict.html).
+- [ ] `devtools::check(".", manual = TRUE, env_vars = c(NOT_CRAN = "false"))`.
+  - Aim for 10/10, no notes.
+- [ ] If check works well enough, merge to main. Otherwise open a PR to fix up.
+- [ ] [Polish NEWS](https://github.com/cmu-delphi/epipredict/blob/dev/NEWS.md).
+  - Some [guidelines](https://style.tidyverse.org/news.html#news-release).
+- [ ] `git checkout main`
+- [ ] `git pull`
+- [ ] `urlchecker::url_check()`.
+  - This may choke on the MIT license url, and that's ok.
+- [ ] `devtools::build_readme()`
+- [ ] `devtools::check_win_devel()`
+- [ ] Have maintainer ("cre" in description) check email for problems.
+- [ ] `revdepcheck::revdep_check(num_workers = 4)`.
+  - This may choke, it is very sensitive to the binary versions of packages on a given system. Either bypass or ask someone else to run it if you're concerned.
+- [ ] Update `cran-comments.md`
+- [ ] PR with any changes (and go through the list again) into `dev` and run through the list again.
+
+Submit to CRAN:
+
+- [ ] `devtools::submit_cran()`.
+- [ ] Maintainer approves email.
+
+Wait for CRAN...
 
-TBD
+- [ ] If accepted :tada:, move to next steps. If rejected, fix and resubmit.
+- [ ] Open and merge a PR containing any updates made to `main` back to `dev`.
+- [ ] `usethis::use_github_release(publish = FALSE)` (publish off, otherwise it won't push) will create a draft release based on the commit hash in CRAN-SUBMISSION and push a tag to the GitHub repo.
+- [ ] Go to the repo, verify the release notes, and publish when ready.

_pkgdown.yml

@@ -22,20 +22,20 @@ navbar:
   type: light
 
 articles:
-- title: Get started
-  navbar: ~
-  contents:
-  - epipredict
-  - preprocessing-and-models
-  - arx-classifier
-  - update
+  - title: Get started
+    navbar: ~
+    contents:
+      - epipredict
+      - preprocessing-and-models
+      - backtesting
+      - arx-classifier
+      - update
 
-- title: Advanced methods
-  contents:
-  - articles/sliding
-  - articles/smooth-qr
-  - articles/symptom-surveys
-  - panel-data
+  - title: Advanced methods
+    contents:
+      - articles/smooth-qr
+      - articles/symptom-surveys
+      - panel-data
 
 repo:
   url:
@@ -79,15 +79,15 @@ reference:
       - grf_quantiles
   - title: Custom panel data forecasting workflows
     contents:
-    - epi_recipe
-    - epi_workflow
-    - add_epi_recipe
-    - adjust_epi_recipe
-    - Add_model
-    - predict.epi_workflow
-    - fit.epi_workflow
-    - augment.epi_workflow
-    - forecast.epi_workflow
+      - epi_recipe
+      - epi_workflow
+      - add_epi_recipe
+      - adjust_epi_recipe
+      - Add_model
+      - predict.epi_workflow
+      - fit.epi_workflow
+      - augment.epi_workflow
+      - forecast.epi_workflow
 
   - title: Epi recipe preprocessing steps
     contents:

vignettes/.gitignore

@@ -1,3 +1,4 @@
 *.html
 *_cache/
 *.R
+!_common.R

vignettes/_common.R

@@ -0,0 +1,23 @@
+knitr::opts_chunk$set(
+  digits = 3,
+  comment = "#>",
+  collapse = TRUE,
+  cache = TRUE,
+  dev.args = list(bg = "transparent"),
+  dpi = 300,
+  cache.lazy = FALSE,
+  out.width = "90%",
+  fig.align = "center",
+  fig.width = 9,
+  fig.height = 6
+)
+ggplot2::theme_set(ggplot2::theme_bw())
+options(
+  dplyr.print_min = 6,
+  dplyr.print_max = 6,
+  pillar.max_footer_lines = 2,
+  pillar.min_chars = 15,
+  stringr.view_n = 6,
+  pillar.bold = TRUE,
+  width = 77
+)