Better formatting for notebooks that "Open in binder"

[hyanwong]

I've just tested the "Launch binder" rocket-shaped icon in the top left of e.g. https://tskit.dev/tutorials/basics.html and it works, hurrah! That's great, because people can simply run the tutorial material themselves easily now.

But the formatting of the sections, links to online docs, etc doesn't work yet (screenshot below)

There might be some jupyterbook flags that could be used to e.g. convert e.g.

{func}`~tskit.load`

To an actual link in the compiled notebook, and to change

:::{note}
This is a note
:::

into a note, a bit like seems to be done here: https://nbsphinx.readthedocs.io/en/0.8.6/markdown-cells.html (I'n not sure if that's the tool we should use)

[jeromekelleher]

@grahamgower and I spent some time on this for the msprime documentation and we decided that the binder functionality wasn't worth it. The notebooks we're developing aren't designed to be interactive, and they look crap whatever you do.

We should turn off the Binder links.

[hyanwong]

OK, but it is quite nice that they do actually run in binder, albeit with rubbish formatting.

I suspect that people might want to run the notebooks either locally or e.g. as a Google Colab version, so perhaps instead of a binder link we should have some instructions for how to run the notebooks locally or on a remote server? Or even provide an alternative version that works like that? Since we are using some pre-constructed tree sequences for the tutorials, there should be an easy way to get a notebook running that uses these tree sequences, ideally without requiring the user (e.g. a masters student) to actually clone the entire repo. Just downloading the thing as an .ipynb presumably won't work for this reason?

[hyanwong]

One way we could get around this, which I think would be quite flexible, is to have an easy way of loading a tree sequence from a URL. It would be nice to be able to do

ts = tskit.load(urllib.request.urlopen("https://tskit.dev/tutorials/data/basics.trees"))

or even have a "url" argument to tskit.load:

ts = tskit.load(url="https://tskit.dev/tutorials/data/basics.trees")

Then people could simply copy-and-paste the cell content, and it should all work.Do you think this is a reasonable functionality to add to tskit.load, @jeromekelleher ? And if so, how do we expose these (very small) tree sequences so that they can be seen at https://tskit.dev/tutorials/data/xxx.trees?

[jeromekelleher]

We spent quite a lot of time on it @hyanwong because it would be nice, but there are loads of technical issues involved in getting the environment working properly, it rarely actually works as expected and it looks rubbish. It's just not worth the effort. It's definitely not worth compromising the effectiveness of the tutorial content for the sake of making them runnable, or of the (very significant) effort required to make them runnable by other people.

Adding url support to tskit is a separate issue, feel free to open an issue on tskit for this if you think it's useful.

[hyanwong]

We spent quite a lot of time on it @hyanwong because it would be nice, but there are loads of technical issues involved in getting the environment working properly, it rarely actually works as expected and it looks rubbish. It's just not worth the effort. It's definitely not worth compromising the effectiveness of the tutorial content for the sake of making them runnable, or of the (very significant) effort required to make them runnable by other people.

Yeah, I can definitely see that. Some instructions for how to get a runnable notebook working would probably be helpful though (even if it is "clone the repo, install conda, etc"). However, I do think the URL stuff might well be a decent solution to all this hassle, as well as being more general useful, so I'll open an issue.

[hyanwong]

Closing in favour of #116

[jeromekelleher]

Yeah, I can definitely see that. Some instructions for how to get a runnable notebook working would probably be helpful though (even if it is "clone the repo, install conda, etc").

I don't think it's worth it - people will spend a lot of time on it trying to document it, and then when people try to use it will most likely fail and the user will end up more frustrated than if they never thought it was a possibility in the first place.

[jeromekelleher]

Reopening until the Binder link is disabled (PR on the way)