knitr::opts_chunk$set( collapse = TRUE, comment = "#>" )
This package should be a living, evolving tool and a set of living documents. This vignette describes how this package is being developed and thus how it can be extended and updated.
This package is being developed on Github using the workflow suggested Hadley Wickham's R Packages book and implemented by the usethis
package.
The development roadmap is stored in a primitive form in Github Issues.
Releases (of the source package only) are made available in the Relaeses part of Github, meaning a last stable release can be installed using e.g. remotes::install_github("scholaempirica/reschola", ref = github_release())
regardless of how messy the current state of the repository master branch is.
Big changes or new features should be built in branches.
Try to use as few as is reasonable; avoid obscure ones. Prefer CRAN releases.
Prefer versions where CRAN binaries are available for all platforms.
Pre-commit checks are used to ensure that broken code is not committed.
Commits are only pushed when they pass local R CMD checks with no errors or warnings. Checks are then run on Travis on an Ubuntu system as part of building the website. For releases (e.g. v0.1.0) checks are run on r-hub.
An exception to the automatic continuous integration and check pipeline is the chart.Rmd
vignette, which is prebuilt locally using vignettes/prebuild.r
from charts.Rmd.orig
to ensure fonts are used correctly. (The approach is taken from ropensci as described in this blog post and applied in this package)
Currently no tests are included or test coverage tracked, but vignettes are written so as to cover and implicitly test the basic functionality of the package.
MacOS and Windows binaries of stable (minor and patch, so X.Y.0 and X.Y.Z where Z != 9000) releases are made available on the Schola drat package repository.
This is done manually, using the ptrr::insert_package_into_drat()
utility in the ptrr
package but can be without it by downloading built binaries output by r-hub and inserting them into the gh-pages
branch of the drat
Github repository using the drat
package.
See installation instructions in README.md for how to install these binaries.
The continuous integration pipeline (Travis CI and Github Pages) means that whenever code is pushed to Github, the documentation of the package is converted to a website by the pkgdown
package and published on scholaempirica.github.io/reschola via the gh-pages
branch of the repository.
In principle, small changes (e.g. correcting typos) can be made in the web interface on Github by any member of the scholaempirica Github team. This is done by going to the relevant file on Github, clicking the pencil icon, and editing the text. When saving changes, Github prompts you to make a commit, which triggers a rebuild and republish of the web documentation.
Function documentation is contained in the functions' R files in R/
, vignettes are in /vignettes
. The charts.Rmd
/charts.Rmd.orig
vignette requires special treatment - see above.
Big changes should be done after cloning the repo and opening in RStudio, ideally on a separate branch.
The vignettes are in principle Rmd files with a special YAML header so can be reused and republished anywhere and in any format if needed.
template.docx
in inst/rmarkdown/templates/schola_*/resources/
vignettes/*.Rmd
reschola
templates: inst/rmarkdown/templates/schola_*/skeleton/skeleton.Rmd
base$knitr$opts_chunk
bits in R/rmarkdown_output.R
inst/rstudio/templates/project
and R/rstudio_project_bindings.R
; consult https://rstudio.github.io/rstudio-extensions/rstudio_project_templates.html. inst/rstudio/templates/project/schola_project.dcf
sets up the dialog and lists files which will be opened in the new projectR/{function_name/group}.R
; consult https://r-pkgs.org/man.html on documenting things.R/fonts.R
The package architecture and many components draw heavily on ratlas
by @ratlas-aai/@wjakethompson (Jake Thompson), and on hrbrthemes
by Bob Rudis (@hrbrmstr).
You can see Jake's Rstudio::conf talk on ratlas
at https://resources.rstudio.com/rstudio-conf-2020/branding-and-packaging-reports-with-r-markdown-jake-thompson.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.