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
which specifies the details of the binder configuration.
It also provides a basic description of the gallery contents.
Contributing to an Existing Gallery¶
You can contribute to an existing gallery by either modifying one of the existing notebooks or adding a new notebook. Since every gallery is a GitHub repository, you can contribute by making a pull request.
Creating a New Gallery¶
To create a new gallery, you will need to create a new repo following the example gallery template.
Click the big green button to create a new repository following the template.
Remove the dummy content and add your content.
Add a custom
thumbnail.png, a 200 x 200 px image which represents the gallery contents.
Now push your changes, e.g.:
git push origin
At this point, a GitHub Action will execute your notebooks on the binder.
Click the “Actions” button on your repository page or navigate to
and wait for the build to finish. The build may fail to complete before the repo is
added as a submodule to
pangeo-gallery. Once you set that up below, you can click
the most recent failed “Binderbot Build” in the Actions list, click “Binderbot Build”
in the left sidebar, then click “Re-run jobs” in near the top right of the page. This
will run the GitHub Action again. Alternatively, you can push another commit to your
notebook content and the action should automatically run again.
You also need to add your repo as a submodule to the Pangeo gallery repo, located at https://github.com/pangeo-gallery/pangeo-gallery. There are two ways to do this.
Add a submodule via git and do the work yourself
Add a submodule via a GitHub issue and let the CI system do the work
Add a submodule via git¶
Fork the gallery repo.
Clone your fork.
Create a feature branch.
Add your repository as a submodule, e.g.:
git submodule add -b binderbot-built \ "https://github.com/pangeo-gallery/example-gallery.git" \ repos/pangeo-gallery/example-gallery
Commit and make a PR to the upstream gallery repo.
Add a submodule via a GitHub issue¶
Go to the pangeo-gallery repo
Go to the Issues section and make a new issue
The only text in the issue comment should be:
<binder_repo> will match the entry in the
binder-gallery.yaml file described below.
Sometimes, the GitHub Action to add your repo as a submodule will fail. We can work with you to identify and fix issues. Sometimes, making a new issue in the same way as above is necessary to correctly reload new settings from your gallery repo.
Config File Specification¶
All example galleries must contain a file called
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.
The heading used when displaying the gallery
A short paragraph describing the gallery contents
Location of the gallery website repo on GitHub.
Url for binder service in which to run the notebooks.
Github repository which contains the environment configuration. (Can be the example repo itself or an external repo.)
Branch, tag, or commit within
Used by GitHub workflow to determine where to push the output of the
binderbot built notebooks. Default (