Improve documentation for new users not working on the master branch

I spent way too much time today trying to construct a url to launch my repo on mybinder.org from a branch other than master before someone pointed me to nbgitpuller and I was able to generate a working link in a matter of minutes. I was surprised that I wasn’t able to find this site through the mybinder docs or even google. I’d like to add a sentence or two sharing this resource to the “Getting Started” page of the docs, but wanted to make sure there wasn’t a reason it was explicitly excluded from the docs currently.

Hi! Can I ask why filling in the desired branch name in the box on the mybinder.org form (highlighted below) didn’t work for you?

1 Like

Of course. The issue I had with using the mybinder.org form was that it didn’t actually connect to my repository content, instead only displaying the binder configuration files:

The content does show up if I use the master branch, but I was trying to test the binder environment setup, which currently only exists on my working branch. I don’t want to point to one specific notebook (they’re all in subdirectories anyway), and adding the repo url as a “path to a notebook file” did not include them either. I’m also starting the instance into JupyterLab, which resulted in the same issue (no repo documents) when I added ?urlpath=lab to the url, as indicated in the docs. So I’d taken to trying to manually generate a url from an older example I had in order launch a binder running JupyterLab and where the repo content showed up.

I’m setting things up for this public repo, which uses a docker image to provide environment settings.

Are you using two repos? One you’re testing with and the one you linked in your above post?

The Dockerfile in the repo you linked looks very bare to be used with mybinder.org. We recommend people start from the minimal Dockerfile example and built out to make sure everything will run properly.

But I can’t see where you’re testing with environment.yml, etc?

No, it should all be one repo - the link points to the particular branch of the repo I am testing. The image shows what happens when I open that repo+branch combination from the mybinder-dot-org form (I’m a new user so I can only have two links in my post).

The Dockerfile points to an existing Docker image, I believe. @scottyhq - can you comment on that if I’m mistaken? After some digging, the notebook package is included within our docker setup (in the pangeo-data docker base images, which the repo that creates the referenced docker image uses).

Oh, then I have no idea where the environment.yaml, etc, in your screenshot are coming from :thinking: or indeed where your content files are going to either. Is the pangeo base image built to work with mybinder.org?

Looking at the GitHub Actions the second repo uses to build the image, I will mention that we have a repo2docker action that will automatically builds the images and create a mybinder.org compatible Dockerfile, so perhaps that may help untangle this?

Hi @sgibson91 @JessicaS11! I think the key here is seperating the computational environment versus content (whether they are on separate branches, or separate repos) as described in this forum post Tip: speed up Binder launches by pulling github content in a Binder link with nbgitpuller.

I suppose this is still considered ‘advanced’ usage. Plus it only works if your environment has nbgitpuller installed. In any case, I think the link generator on the nbgitpuller docs is really handy! Perhaps it’s worth linking to here https://mybinder.readthedocs.io/en/latest/using.html ?

1 Like

Yes, we should definitely include a usage example in the context of separate env and content. I think I just got all confused over this particular example! :sweat_smile:

1 Like

oh shit that’s a good idea! I had not thought to put the “environment” and the “computational content” on two different branches. That’s clever!

this is definitely an “advanced use case” which is why it isn’t documented well, but I think we should definitely improve that documentation. I’m +1 on finding ways to make this pattern more discoverable in ways that don’t also complicate people figuring out how to build repositories the “default” way.

1 Like

Thanks for clarifying that for us all! I’d be happy to put together a draft PR that adds a short note on this use case to the docs. Thoughts from those more familiar with the docs on where to put it? My instinctual place to look for the info yesterday was Getting Started > Common Usage Patterns, How-To Guides, or Tutorials. I didn’t think to look at any of the “speeding things up” links, though it seems like the discussion there ultimately tangentially addressed this issue and could be referenced.

I’d be happy to review a PR like this, I think you are in the best position to know where to put it since you just went through the exercise of “looking for” the information!

My thinking is:

  • document something in the location where others will instinctively look for it
  • if there are many possible places, document it in one place and add lots of cross-refs to it
2 Likes

Github conventionally uses the gh-pages branch as a “reserved” branch for constructing Github Pages docs related to a particular repo. I’ve idly wondered before about whether we could take a similar approach for defining a “Binder build” branch?

via

I think the it would add some complexity to the build process, but it’s an interesting idea. I guess the question is whether this pattern of separating environment and content is something we want to actively promote etc by making it easier on the tech side