Reproducible web stack

This is a stack of tools that have served me well to generate reproducible websites. Some defaults were set to make things more seamless and I added some files to show it works. This is a fairly opinionated approach and your mileage may vary.

The website generated from these scripts can be viewed at:
https://rubenarslan.github.io/repro_web_stack

Requirements to get started

• RStudio 1.*
• R 3.*
• Git (should already be installed on Mac OS Mavericks and above)

Set up

Here's how to set up:

1. (Optional, if you have a Github account already or are willing to create one). Fork this repository (top right).

2. Open RStudio. In the top right menu "project menu", click new project.

3. In the dialog box that appears, click "Version Control". Copy-paste the URL from your repository (it will be https://github.com/rubenarslan/repro_web_stack except with your username, if you forked it). Create the project (you can pick a different name if you'd like).

4. In RStudio packrat should start installing packages, if not, consider running

   packrat::restore() # this should run by default if you open the project in an up-to-date RStudio version
   packrat::disable() # because packrat is a bit immature, it's probably easier to only turn it on at the end, when you archive your project. It may make sense to put up with the immaturities if you're working on a lot of projects in parallel.

5. Now try whether you can generate the website by clicking "Knit" in the file 1_wrangle_data.Rmd, then try the other files, then modify them to suit your project.

Configuration

Here's a few files you might want to edit:

1. .zenodo.json this file contains the metadata that will be used to describe your releases on Zenodo. Add the project name and the authors in this file.

2. _site.yml here you can set up a few global settings for how your site should look like. More information.

3. 0_helpers.R - here I load a few packages that I tend to always use. I think it makes sense to load a basic set of packages in this helper file and include it everywhere. Load order matters hugely in R (especially when you use dplyr, which has lots of name conflicts with other packages) and it can simplify things for you, when you know the load order. I've also set a few defaults here that make sense to me.

4. The name of the .Rproj file to something descriptive of your project (and correspondingly, the name on Github).

Releasing to Zenodo

To release to Zenodo via the API, your repository needs to be public. Then, go to Zenodo, connect your Github account, flip the switch next to the project name and make a release on Github. It will automatically be uploaded to Zenodo and you will get a DOI, like this . I usually release the gh-pages branch, because that's the readable part.

If you don't want your R-code to be public, but only the HTML files, you can either: download a zip of a private release of your gh-pages branch and upload that to Zenodo by hand or you can make a separate, public repository for your HTML files and check this out in your _site directory.

Notes

Github branches

The best way I've found to manage the resulting HTML-files is to keep them in a sub-directory (called _site by default) and to checkout the gh-pages branch for your repository in that directory as a submodule. I've set it up so that this the default for this project, so it should work out of the box.

I've found SourceTree handles Git with submodules in a quite user-friendly manner, RStudio not quite yet.
RStudio says you can also use a subdirectory called "docs/" in the master branch, instead of checking out gh-pages, but that doesn't appear to work if you're a regular Github user.