Contributor Guide

The site is organized into galleries, each containing one or more notebooks. Each gallery is stored in a standalone GitHub repository. All notebooks within a gallery should share a similar theme (for example, Pangeo for Physical Oceanography) and must use the same Conda environment.

Galleries are “built” using binderbot. Binderbot takes all the notebooks in the gallery, executes them inside binder, and saves the output to a dedicated branch within the repo. Each gallery contains a configuration file called binder-build.yaml, which specifies the details of the binder configuration. It also provides a basic description of the gallery contents.

Config File Specification

All example galleries must contain a file called binder-build.yaml. An example file is shown below:

---
name: Example Gallery
description: >-
  An example gallery of notebooks used for debugging the Pangeo Gallery
  infrastructure.
gallery_repository: pangeo-gallery/pangeo-gallery
binder_url: "https://binder.pangeo.io"
binder_repo: pangeo-gallery/default-binder
binder_ref: master
binderbot_target_branch: binderbot-built

The fields are defined as follows.

binder-build.yaml

Parameter

Description

name

The heading used when displaying the gallery

description

A short paragraph describing the gallery contents

gallery_repository

Location of the gallery website repo on GitHub. Default pangeo-gallery/pangeo-gallery should probably not be changed.

binder_url

Url for binder service in which to run the notebooks.

binder_repo

Github repository which contains the environment configuration. (Can be the example repo itself or an external repo.)

binder_ref

Branch, tag, or commit within binder_repo which contains the binder environment configuration.

binderbot_target_branch

Used by GitHub workflow to determine where to push the output of the binderbot built notebooks. Default (binderbot-built) should probably not be changed.