lockedata / starters

R Package 📦 for initializing projects for various R activities :nut_and_bolt:

starters

This package is designed to take away some grunt work around setting up new projects.

All projects get setup with Git, GitHub and Travis by default.

• Use create_package_project() to setup a project with code coverage, vignettes, unit testing etc. out of the box

• Use create_analysis_project() to get a project ready for a typical analysis project. It includes renv to help with reproducibility.

• Use create_training_project() to get a project ready for delivering training that often involves handouts and presentation materials. It includes renv to help with reproducibility.

All functions implement name validation based on the guidance in “Writing R Extensions”, “[The name] should contain only (ASCII) letters, numbers and dot, have at least two characters and start with a letter and not end in a dot”.

Setup for starters

Installation

remotes::install_github("lockedata/starters")

start_here() function

Run

starters::start_here()

This function checks different aspects of your setup (git installation, gitconfig, GITHUB_PAT, DESCRIPTION default values, GitHub username guessing), that will help automatic steps later on. Most of these aspects are inspired from usethis setup article. For each aspect, if your setup needs improvements an informative error message will be thrown so you might be able to know how to proceed.

RStudio gadget

If you want to set up a project without using the R functions, @jonmcalder made a nifty RStudio addin. Install the package to get it added to your RStudio instance.

Related work

Other R tools (not necessarily active, vet them first) useful for starting new projects.

• usethis in general, create_project() and create_package() in particular. starters actually depends on usethis.

• skeletor, An R Package Skeleton Generator.

• mkrpkg, Template for making R packages.

• mason, A friendly craftsman that builds you great R packages.

Contributing

General info

Wanna report a bug or suggest a feature? Great stuff! For more information on how to contribute check out our contributing guide.

Please note that this R package is released with a Contributor Code of Conduct. By participating in this package project you agree to abide by its terms.

Up for grabs

Make sure to check out the Issues tab in GitHub! We’re making this project a great place to start contributing to R packages. We will help you through the process.

starters's Issues

Add pkgdown to package creation

We should facilitate pkgdown as it's nifty so that folks can build a package site more easily

Error: project name with hyphen and underscore

Hi, thank you for your package. Today I got an error when I tried to create a new package with underscore or hyphen, as below:

pRojects::createTrainingProject(name = "sample-one", 
dirs = c("data", "handouts", "slides"), 
handoutEngine = "rmarkdown", 
slideEngine = "rmarkdown", 
travis = F, packrat = F, git = F, readme = TRUE)
#> Creating skeleton
#> Error: sample-one is not a valid package name: it should contain only
#> ASCII letters, numbers and dot, have at least two characters
#> and start with a letter and not end in a dot.

This code created an empty folder with the name sample-one. Do you have any idea? Sometimes, it is inconvenient without the hyphen to name a project. Now my solution is a name without the hyphen first, then rename it later.

Re-use GitHub

At the moment I removed the Travis and coverage activation parts because they depended on the project already using GitHub.

use_github() can't work on Windows yet because of git2r. I'll either wait for it to work on all OS, or re-write some Travis/coverage stuff, just copy pasting templates at creation, and browsing the right pages afterwards.

@stephlocke if you re-install pRojects now, you get less when creating a package, but this will be fixed soon, sorry about that.

Facilitate use of drake?

https://github.com/ropensci/drake

Integrate fledge to package creation?

https://github.com/krlmlr/fledge

Have a look at the following packages

https://github.com/noamross/mkrpkg by @noamross

`styler` pre-commit hook

Auto-clean code before it get's committed perhaps?
http://styler.r-lib.org/

Training: Add production scripts

For the skeleton docs (#1), have a script that produces them and sends to gh-pages branch or docs/

This could then be added to .travis.yml

Default earliest R version

Have some default value for earliest R version to go in R DESCRIPTIONs

Analysis: Add production scripts

For the skeleton docs (#2), have a script that produces them and sends to gh-pages branch or docs/

This could then be added to .travis.yml

all functions should reset the project to what it was

After checking there was a project set, of course.

Otherwise right now you end up with the project (for usethis) to be set to the one you created, not the one you started from.

Analysis projects: Create skeleton docs

Create some templates that can be added to createAnalysisProject

why the call to packrat:::augmentRprofile?

In https://github.com/lockedata/pRojects/blob/afa88b2923aa9e5858889f8b0c17e942d89f9fb6/R/createBasicProject.R#L32

The line after that calls packrat::init and it seems that it calls a function that calls augmentRprofile https://github.com/rstudio/packrat/blob/eaf443593fc48ca2a3ebc724e3a3297b6a6a9b69/R/packrat.R

But I've close to no packrat experience.

No longer use use_readme_md and use_readme_rmd when creating a package

In createPackageProject https://github.com/lockedata/pRojects/blob/master/R/createPackageProject.R#L26

I'd be in favour of adding an argument readmeFormat that could be "md" or "Rmd" ("Rmd" by default which shall motivate me to set up Travis build of the README 😁 ). Then either usethis::use_readme_rmd or usethis::use_readme_md would be used (with the git hook made by usethis).

I'd moreover make the README creation happen no matter the value of bestPractices because it seems easier than explaining that if bestPractice is FALSE the readme_format argument is ignored.

Add a `createAPIProject`

@hrbrmstr started a project a while ago close to my heart hrbrmstr/swagger.

I'd like to revive that project to generate functions from API definitions produced in swagger - this would enable us to point at a swagger definition and produce not just a package skeleton with best practices but functions too.

• Make sure swagger can generate functions from a definition
• Add dependency on swagger from here
• Write function that accepts a name and a swagger definition and generates a package project with R functions
• Extend the add-in to allow this type of project to be created

Write vignette about package projects

Cover the what and why of the selected use_* statements in createPackageProject and suggest next steps for user

Is there appetite to extend Use Git button to using git lfs as well?

The package currently calls to devtool::use_git() when the Use git option is TRUE. The package also contains the option of including a data folder. git lfs (large file storage) is a useful extension to git that indexes file by type/location, and commits them to git in a safe way that doesn't lock up the repo when it's hosted externally, or slow it down if a large data set changes a lot.

Would it be technically possible to have a use git lfs button? I don't believe devtools has a wrapper to it, so any solution will probably have to be implemented slightly differently. If it were possible, would it be useful/desired?

How to test repo creation

Create a dummy GitHub account for that?

Add usethis wherever possible

• instead of devtools

• to replace part of the code

Does checkpoint really fit in pRojects?

In https://cran.r-project.org/web/packages/checkpoint/vignettes/checkpoint.html I 👀 "Scans your project folder for all packages used. Specifically, it searches for all instances of library() and require() in your code."

At setup time, there's no packages used, only packages specified in DESCRIPTION, so checkpoint does nothing, e.g. if I run it in createTrainingProject I get

Scanning for packages used in this project
- Discovered 0 packages
No packages found to install
checkpoint process complete

and as far as I understood pRojects philosophy, what we'd want is a package that'd get dependencies from DESCRIPTION (and help setup DESCRIPTION, but not bypass that step)? 🤔

Use logo in docs?

I 👀 a logo in images. @stephlocke should I put it in the README? If so assign it to me 😉

Write vignette about training projects

Cover the what and why of the methodology expected by createTrainingProject and suggest next steps for user

Incorporating `goodpractice`

Should we add a pre-commit hook that will run good practice? It might make it so that if only if it passes it would commit - that's probably too onerous.

Perhaps just adding it to the pRojects Suggests?

Remove all the try() from tests

Since we want to have test failures in case of issues, not empty tests?

Improve file path handling

Current iterations of functions assume you want to create a directory below your current one. Modify the functions to allow a path to be provided.

packrat in createTrainingProject

I do not understand

  # Installation dir
  usePackrat <- !methods::hasArg("packrat")
  if (!usePackrat)
    usePackrat <- list(...)[["packrat"]]
  installDir <- ifelse(usePackrat, name, .libPaths())

yet, I need to have a proper look.

Custom templates for DESCRIPTION, .Rproj, README.Rmd etc

Enable people to define a custom templates dir to search first, before relying on devtools defaults

Switch bookdown demo?

We currently use the full bookdown-demo repo, but I'm considering the nookdown-minimal one instead. It means a smaller install and less stuff someone might have to remove.

What do y'all think?

html proofing of pkgdown website

Probably as part of tic.R or so

Why have the external templates live inside the package?

As opposed to copying them from these package installations when using them?

Write unit tests

Re-write all examples

using temporary directories like in tests.

Create a function checking there's no repo with the same name

under the user/org account. That could be used in all functions.

By default generate a cool first commit message in use_git

Using praise. praise::praise("First commit of this ${adjective} project, ${exclamation}!")

add a title parameter to basic and package creation functions

otherwise, the GitHub repo created gets a lame default description.

Automatically populate author info etc in DESCRIPTION

Allow for author name, email etc to be set and then automatically populated in the DESCRIPTION when creating packages. These parameters can be included as function arguments as well, but should ideally be fetched by default so that they don't need to be specified repeatedly - I assume this is possible either by setting these parameters as options or via currying or something like that?

Explore possibility for integration with or leveraging of ProjectTemplate

ProjectTemplate is fairly well established. Obviously it takes things much further in terms of enforcing templates, project structure etc, so I suppose one could view createAnalysisProject() as a more lightweight alternative to it.

Nevertheless, given that it has a fair amount of traction, I figure it's worth considering how we want to approach this functional overlap. Any thoughts on this?

Packrat doesn't play nice with dropbox - is this a problem?

I was running into some problems creating project dirs because of packrat. It doesn't like dropbox doing indexing at the same time as it's doing its thing. I don't think we need to do anything but I'm interested in people's thoughts

* Adding packrat to Imports
Next: 
Refer to functions with packrat::fun()
Initializing packrat project in directory:
- "C:/Users/steph/Dropbox/Locke Data/Locke Data Training/Classification/LogisticRegressionBasics"

Adding these packages to packrat:
            _        
    packrat   0.4.8-1

Fetching sources for packrat (0.4.8-1) ... OK (CRAN current)
Snapshot written to "C:/Users/steph/Dropbox/Locke Data/Locke Data Training/Classification/LogisticRegressionBasics/packrat/packrat.lock"
Installing packrat (0.4.8-1) ... 
Warning: unable to move temporary installation ‘C:\Users\steph\Dropbox\Locke Data\Locke Data Training\Classification\LogisticRegressionBasics\packrat\lib\x86_64-w64-mingw32\3.3.3\file22247e730c1\packrat’ to ‘C:\Users\steph\Dropbox\Locke Data\Locke Data Training\Classification\LogisticRegressionBasics\packrat\lib\x86_64-w64-mingw32\3.3.3\packrat’

Create RStudio add-in for high level functions

This might not be appropriate for the intended audience, but I figure if the primary goal is to prevent unnecessary typing and/or function calls in the process of setting up projects, packages etc, then maybe having these available from a drop-down might be useful. Could potentially even create a Shiny gadget using miniUI in order to facilitate input of the few required parameters for the high level functions.

devtools 1.12 (latest on CRAN) uses different README.Rmd code to dev version

The dev version of devtools has a new README.Rmd template file called omni-README.

We should detect devtools version and pass in the relevant file name for that version to make it compatible with planned changes to devtools.

Change the description in DESCRIPTION

Currently "Manage Project Directories for R Projects" which doesn't reflect well the intended power of the package.

Important especially since the website uses that description as page title.

Training projects: Add skeleton docs

Create some templates that can be added to createTrainingProject

Make snake case function names too

I went kind of old school with createBasicProject() - I feel like we could also offer create_basic_project() for people with aesthetic objections to the old school naming convention without breaking things substantially for any existing users of the package.

This should be doable with extra code at the bottom of the function R files like

#' @describeIn createBasicProject
create_basic_project = createBasicProject

Add name validation

As we use package skeletons, names folks can use are subject to R package naming rules. This causes bad user errors right now e.g. #36 and we should add some validation and documentation around the rules.

https://cran.r-project.org/doc/manuals/r-release/R-exts.html#The-DESCRIPTION-file

Clean up in the event of an error

Currently, we leave a directory lying around if the create*()s fail - we should put a try catch or something in so that if things error along the way the dir is dropped.

Remove the ellipsis when calling createBasicProject

and have the explicit arguments instead?

Spellcheck pre-commit hook

Add ability to include spellchecking via hunspell to projects

Do not check for name availability when the project is not a package?

Or define availability differently then? E.g. not trying to create a repo with the same name as another repo.

remove dependency on unexported tufte function

Write vignette about analysis projects

Cover the what and why of the expected methodology in createAnalysisProject and suggest next steps for user