Package Development Documentation & Sources

[nabrahams1]

This issue is designed to track progress on package development and document improvements and sources of information used in the development process.

Prerequisites

• Package "Check" in RStudio may fail if you don't have the devtools and tinytex packages installed, though it won't say so explicitly (it will fail saying something like "pdflatex not available" and/or "this typically indicates Rd problems"):

  
  install.packages('tinytex')
  library('tinytext')
  install.packages('devtools')
  library('devtools')

### Customizing the DESCRIPTION file

#### Requiring Other Packages
Often packages will need other packages to run.  Example: my package needs httr to execute.  Editing the description file is needed to require loading another package.  But, editing the DESCRIPTION file by hand can be trying, but at least for requiring other packages, this is traight-forward.  To use another package, when editing a project in RStudio I enter the following:

When building packages, add this:

usethis::use_package( "httr" )

This will automatically create an entry in the DESCRIPTION file to load that package.  (or it is supposed to anyhow, testing has not always worked... but this is a start).

To *require* a package is a more strict operation, and uses a slightly different syntax, with the second argument "depends":

usethis::use_package("R6", "depends")

> Note: to change a "depends" to only an "imports", you must manually delete the "depends" line from the DESCRIPTION file, then call usethis::use_package("name") again.

#### Loading files in a specific order: Collate
Some packages have files that require other files, this is particularly true when doing object oriented models where one object class "inherits" another and therefore the "parent" class needs to be loaded first.  This is done by adding an entry in the "collate" field of the DESCRIPTION file.  Collate notes:
- At this time I do not know of a function to manage the Collate line so this has to be done manually.  
- **Note:** From what I can gather, once you start a "Collate" list in the DESCRIPTION file, every file in your R directory must be added to this list or package building will fail.
- More info, see Hadley's section on DESCRIPTION files: https://r-pkgs.org/description.html#description-misc

### R6 Object Classes
- These are a new object oriented programming technique, Rshiuny supposedly is based on this.
- - Basic docs: https://adv-r.hadley.nz/r6.html 
- Doc headers for roxygen: https://roxygen2.r-lib.org/articles/rd.html#r6

[alexwlowe]

Link to Joeys PowerPoint Presentation: https://docs.google.com/presentation/d/10iyh6G8vMmy7YV4xGPkaIQP2WcoVK2NsMdb8VGuJJJY/edit?usp=sharing

Devtools Cheat Sheet: https://rawgit.com/rstudio/cheatsheets/master/package-development.pdf

RStudio Support resource: https://support.rstudio.com/hc/en-us/articles/200486488-Developing-Packages-with-RStudio

Helpful Youtube Videos: https://www.youtube.com/watch?v=qxRSzDejea4 (How to write your own R package)

Adding local package to GitHub repository: https://kbroman.org/pkg_primer/pages/github.html

Hadley Wickham package development ebook (great all around tool) https://r-pkgs.org/index.html

[alexwlowe]

Important pieces of a package

• Description file - Setup of general information (title, description, author, etc.)
• R/ - Scripts and Code
• man/ - documentation for functions (This is what creates the help pages in R Studio)
  • Roxygen headers are also important forms of documentation that link everything together
• Tests (testthat) - testing functions
• NAMESPACE - helps organize package and keep it contained
  • Generated by roxygen
  • Houses exports and imports

Important packages used when creating a package

• devtools
  • document() - creates and updates
• roxygen2
• usethis
• testthat