UpdatingTheGallery

The Tideline Gallery

The tideline "gallery" is tideline's GitHub Pages project page. It always hosts a link to the tideline example mini-app demonstrating the current progress of the repository with demo data supplying the data to drive the visualization.

The tideline repository contains several tools for updating the gallery. The tools are usable by anyone with push access to the tideline repository; at present, this is limited to Tidepool employees. Read on for more information about:

1. setting up the gh-pages branch
2. updating the "current progress" page
3. updating the "gallery" with a (or several) design iterations for consideration

Setting up a gh-pages branch

In this guide, I'll describe all the steps necessary to set up the gh-pages branch, assuming you've already cloned the tideline repository as a directory named 'tideline.' For more information on the motivation behind this strategy of working with GitHub pages branches, see GitHub's guide to manually creating project pages, which is the model for the system.

First, navigate into the tideline repository:

$ cd /path/to/tideline/

Create a fresh clone of tideline in an embedded directory called web/. This is important! All of the tideline gallery management tools assume that your gh-pages branch is contained within a directory named 'web' and located one level down from the main 'tideline' repository folder.

$ git clone git@github.com:tidepool-org/tideline.git web

(Note the final command-line argument in the clone command above, which tells git to put the fresh clone in the directory web/ instead of another tideline/ directory.)

Navigate into web/:

$ cd web/

Create a local gh-pages branch that's orphaned from the rest of the repository branch structure (because the gh-pages code is never expected to integrate back into master, etc.), and remove everything from web/:

$ git checkout --orphan gh-pages
$ git rm -rf .

Now associate your local branch with the upstream gh-pages and delete the master branch because you won't need it in the embedded web/ clone of the repo:

$ git checkout gh-pages
$ git branch -d master

After the checkout, you should see a message from git like the following:

Branch gh-pages set up to track remote branch gh-pages from origin.
Already on 'gh-pages'

At this point git branch should yield only the following:

* gh-pages

And git log should not be empty, but should match the list of commits available via the [github.com UI](https://github.com/tidepool-org/tideline/commits/gh-pages 'Commits on tideline's gh-pages'). Finally, git status should yield a clean working directory. If all of these things are true, you're good to go. \o/

Sidenote: Jekyll

In order to view the tideline GitHub Pages project page locally, you must have Jekyll installed. Follow the instructions provided by GitHub to install Jekyll, then test that it's working by running the jekyll bash script provided on the gh-pages branch:

$ ./jekyll

Jekyll will serve the page at http://localhost:4000/.

Updating the Gallery

There is a Python tool gallery.py in the dev/ directory that provides an easy, interactive interface for inspecting the current items in the gallery, adding new items, or removing an items or items.

The usage of this Python tool can be obtained via python gallery.py --help.