Add Binder execution button with sphinx library

[kurianbenoy]

Issue: #764

Note:

I am able to successfully run the make doc to bring up documentation along with binder button in the website. Yet I am still facing the issue of not having the correct notebook being shown on selecting

Update:

[romanlutz]

@kurianbenoy I spent a few hours comparing this with scikit-learn, and while I don't understand the full picture yet here's something I found:
Binder looks at the repo fairlearn/fairlearn on the main branch. We don't have notebooks/auto_examples/... there, though. Those will be results of the doc build. scikit-learn/scikit-learn doesn't have that directory either, but they have https://github.com/scikit-learn/scikit-learn.github.io/tree/main/0.24/notebooks/auto_examples in their website repo (the equivalent of fairlearn/fairlearn.github.io). When I build it locally that notebooks/auto_examples directory shows up, but Binder doesn't seem to be able to pick it up. I don't know why... @adrinjalali do you have an idea?

The thing about scikit-learn that confused me a lot was them mentioning a scikit-learn/binder-examples repo which has since been deleted, so I created a PR to fix that comment. scikit-learn/scikit-learn#20480

So the good news seems to be we don't need a separate repo for this either.

The other point I'm wondering about is whether the .binder directory at the repo root needs to exist on the referenced branch for this to work. I will try this on my branch as soon as I can (although this week may be tricky) and then use my fork & branch name in the binder config rather than the fairlearn/fairlearn repo with main. If you want you could try that as well.

[adrinjalali]

@lesteve would you be able to give us a hint? Binder is a bit puzzling us here.

[lesteve]

The scikit-learn approach for sphinx-gallery + Binder is to generate the notebooks inside the Binder docker image through a postBuild step, see https://github.com/scikit-learn/scikit-learn/blob/main/.binder/postBuild.

IIRC the standard sphinx-gallery + Binder approach is to have the notebooks in the .github.io website but that was not convenient for scikit-learn (I don't exactly remember the details why I have to admit, edit: maybe to switch between stable and dev doc?, not sure at all ...).

[kurianbenoy]

I also feel trying with postBuild configuration, can resolve the issue. I will try it out and let you know.

@romanlutz thanks for sharing your observation. I am just sharing an observation, ie if you look at the auto_examples generated in scikit-learn website repository you will see only ipython notebooks, while the auto_examples generated in docs folder in
Fairlearn repo contains python file, rst file, ipython notebooks etc.

Also just a doubt is CircleCI failing because of the issue #819 ?

[romanlutz]

I believe one of the issues with this was sphinx-multiversion which we're no longer using, so we could try this again with the latest state of the repo if someone is up for it. It's been a while, but @kurianbenoy is more than welcome to try again if that's still something they're interested in (?) Let us know!