Allow to launch from binder with nbgitpuller

[fmaussion]

This is a follow-up to a post I opened on meta

For reasons discussed at length here, I'd like my JupyterBook notebooks to be launched via gitpuller in another binder-ready repository.

This is quite niche I suppose, but if you'd agree to have this as a feature I'd be happy to submit a PR for this functionality. The exact API is a bit fuzzy in my mind though.

I'd start by adding an option here:

https://github.com/executablebooks/sphinx-book-theme/blob/72f417b07f08816e7179d85dff2e5c7b2e5f41e7/sphinx_book_theme/launch.py#L97-L109

by adding something that could look like:

    if binder_repo and binderhub_url:
        url = (
            f"{binderhub_url}/v2/gh/{binder_repo}/master?urlpath=git-pull?"
            f"repo={repo_url}%26amp%3Bbranch=master%26amp%3Burlpath={ui_pre}/{repo}/{path_rel_repo}%3Fautodecode"
        )
        context["binder_url"] = url

It starts to become quite dirty at the moment where you'd like fine tuned control on the branch to use on the binder repo, etc.

Just let me know what you think. I have a patched version that does what I want (book) and I guess that I could also get what I want by writing an extension to sphinx-book-theme.

[fmaussion]

[sorry for the noise]

Alternatively, could you maybe point me to a way to change context["binder_url"] from within my book repo, at build time? It would allow me to override the url without messing around with a fork of sphinx-book-theme

Thanks!!!

[choldgraf]

@fmaussion could you just manually over-ride via custom Sphinx configuration, like here: https://jupyterbook.org/advanced/sphinx.html#manual-sphinx-configuration ?

[fmaussion]

Thanks @choldgraf ! I'm afraid I don't understand sphinx well enough to see what you mean... To me it looks like I need to execute some python code after that sphinx-book-theme has done its stuff?

By looking at sphinx-book-theme, the path I'm exploring right now is to have a very trivial sphinx extension ("update-hub-url"), which would have it's own __init__.py and would then have something like:

def setup(app: Sphinx):

    # Configuration for Juypter Book
    app.connect("html-page-context", update_binder_urls)

with update_binder_urls my own code which would mimic and overwrite parts of sphinx-book-theme's add_hub_urls?

If my extension code is running after sphinx-book-theme itself and sill has access to the info it needs from it (repo_url, etc), this could work I think?

[jlperla]

Yes, this is pretty important for having a jupyter version of lecture notes in a self contained and cloneable repo, with the environment or manifest files? Not sure how nbgitpuller could work otherwise?

Or are you saying thereis a workaround? In my mind, binder is just one of multiple nbgitpuller based ways to trigger things from the same repo and it would just another in a list e.g https://github.com/executablebooks/jupyter-book/issues/1253

[jlperla]

@mmcky thoughts?

[mmcky]

@jlperla currently for quantecon projects we are building a set of notebooks using sphinx-tojupyter and gh actions then committing them to a <repo-name>.notebooks repository which contains an environment.yml to support binder deployments. We have binder links to launch them from the html. The idea behind this route for quantecon was to have a repo that was cache ready in binder including the notebooks for quick loads on binder.

But I think I can see the use case here for having a default / universal environment and then use nbgitpuller to populate with a notebook to run once the binder instance is loaded?

[rabernat]

Big 👍 to this idea!

I am updating my book for Earth and Environmental Data Science and I'm really wishing for this feature. I would like to be able to launch the book notebooks into a binder with the images coming from https://github.com/pangeo-gallery/default-binder. In the Pangeo community, it is becoming common practice to separate the environment repo from the content repo. Unfortunately jupyter book + sphinx book theme don't support this right now.