search

executablebooks / sphinx-thebe

A Sphinx extension to convert static code into interactive code cells with Jupyter, Thebe, and Binder.
https://sphinx-thebe.readthedocs.io/en/latest/
MIT License
28 stars 15 forks source link

Document how to dynamically configure git branch in the binder URL #40

Open akhmerov opened 3 years ago

akhmerov commented 3 years ago

Link to the documentation you'd like to improve

https://sphinx-thebe.readthedocs.io/en/latest/configure.html

What to improve

After #17 is merged, we should document how to make sphinx provide the current git branch in generating the binder link.

Implementation

See https://github.com/executablebooks/sphinx-thebe/issues/40#issuecomment-907687684 for some ides from @akhmerov

choldgraf commented 3 years ago

Thanks! If you could, can you add a short description of what the change would actually be? I'm still not quite sure what it means to "make sphinx use the current git branch".

akhmerov commented 3 years ago

The scenario I consider is as follows:

  1. The user makes a PR introducing an API change to the library
  2. The CI builds preview documentation for the PR. Because the docs are built in the checked out repo, everything works :heavy_check_mark:
  3. The docs use sphinx-thebe thebe, which in turn is configured to use a binder URL.

State of the art:

Binder URL points to the default branch, and thebe fails in preview docs.

Possible improvement:

The binder URL is automatically determined during build, and the branch parameter of the binder URL is computed using something like git rev-parse --abbrev-ref HEAD. This ensures that the correct binder branch is used.