richfitz/ghwiki

Tools for pushing files generated by R to a github wiki

Wiki Workflow

This package sets up a lab notebook on a GitHub wiki by running a series of R scripts and knitr documents, collecting figures and updating a wiki. It has grown out of a set of scripts, but is currently used across many of my (not-yet-open) research projects.

The wiki for rodeint is updated using ghwiki. This page was generated from this script and can be recomputed and updated by running a single command.

ghwiki needs to be used within a project that is a git repository. The git repository must have a github remote, and the first remote that has a github url will be used. The remote must already have a wiki.

Install with (from R)

devtools::install_github("richfitz/ghwiki")

Initialise with

Rscript -e "ghwiki::init()"

This will also clone the github wiki into a directory 'wiki' in the project root. If the command failed (e.g., the wiki was not initialised yet), pull down the project wiki manually with:

make wiki_clone

Add names of R or Rmd scripts to the file .wiki_scripts. A template is generated by running the command above. Blank lines and lines beginning with "#" are ignored, and whitespace is trimmed. If .md files are added, they will be copied to the wiki, along with any figures named following the same conventions we convince knitr to follow. At the moment, any file not ending with .R, .Rmd or .md is simply ignored.

Run

make

to run all the scripts listed in .wiki_scripts, generating md files, figures etc. A bunch of knit tweaks are applied to normalise figure paths, improve default settings, etc.

Run

make wiki_update

to update the local copy of the wiki repo, and

make wiki_publish

to push it up. You're on your own with resolving conflicts. Other make targets:

• make clean -- clean up generated .md and .Rmd files.
• make wiki_rollback -- undo a commit in the wiki repo
• make wiki_reset -- destructively clean up an unclean state in the wiki repo

Other commands can be run via ./.ghwiki:

• ./.ghwiki reset_to <SHA> -- move the wiki to a particular SHA (can undo a rollback this way)
• ./.ghwiki git [commands] -- run git commands in the wiki repo (e.g., ./.ghwiki git log)

And yet more commands via ./.ghwiki scripts

• ./.ghwiki scripts list -- list of scripts that we know about
• ./.ghwiki scripts base -- basename of the scripts (without extension)
• ./.ghwiki scripts generated_Rmd -- Rmd files that are candidates for deletion during cleanup
• ./.ghwiki scripts targets -- list of md files that will be generated by make.

If you get fed up with typing ./.ghwiki (which gets tedious) run

Rscript -e "ghwiki:::install_scripts('~/bin')"

which will install the scripts ghwiki into "~/bin" (assuming that it exists!). If that is in your $PATH then you can run ghwiki git log and things like that. Note that these scripts just redirect to the true scripts within the package, so can be left in place through package upgrades -- the scripts that are run are those in the package.

ghwiki's Issues

Equation support

pandoc with --mimetex, then use http://www.forkosh.com/mimetex.html and do rewriting?

Local rendering

See grip, which looks really nice for locally rendering things.

Might need a small amount of tweaking to really work on an wiki, but that could be as simple as generating a README.md file with the current contents.

Installing on OSX had some issues with permissions (had to sudo chown -R <user> /Library/Python/2.7/var/grip.server-instance to allow css to work, and only root could open in general).

Does not currently work with Rmd files

Install scripts as ghwiki, not wiki.sh

Will be easier to remember I think.

Ignore files

Add wiki to .gitignore and to .Rbuildignore

Automatically generate gitignore files

These should be easy to add.

Create wiki if it does not already exist

Should be able to hit the url

https://github.com/<user>/<repo>/wiki/_new

Perhaps with RCurl?

Enable "prefix" within a directory

Wikis don't really have nice directory structures, but we can kind of enforce one with prefixes. It would be nice to have some file (perhaps a little config file) that sets options including a prefix that is added to each name before copying to the wiki. Doesn't need to change anything else though.