Make the Quickstart docs a Pluto notebook

[sethaxen]

Pluto is a reactive notebook environment. While some elements are always reactive in the browser, the entire notebook can be made interactive in 2 clicks by launching Binder in the background to run the notebook. This PR tests out a Pluto implementation of the Quickstart. The result should be that uses can interact with the Quickstart in several ways. However, the required packages may take so long to load that this isn't that useful in the end.

[sethaxen]

Binder takes 1-2 minutes to load, and then after about 5 minutes, the Pluto Server stops, presumably because it's taking too long to load everything. I'll leave this PR as is for now, and maybe in the future this will load faster. One way to get faster loading is to have several PPL-specific quickstarts: one for Turing, one for CmdStan, and one for Gen.

[ahartikainen]

Can this use the same hack we had for StanCon? (precompile notebook environments with dummy repo?)

cc @OriolAbril @canyon289

[OriolAbril]

It probably makes more sense to use a sandbox repo with binder for docs than for stancon (I don't expect anybody to still be running that notebook). I can help with that, and I tried to document what I did at https://github.com/arviz-devs/arviz_misc/tree/master/stancon_2020#serve-slides-for-presentation.

[ahartikainen]

That was the hack I was talking about (sandbox-repo)

[sethaxen]

Great! Haven't gotten to look at these repos yet, but just wanted to leave here, this is the approach Pluto uses to get Pluto notebooks on binder: https://github.com/fonsp/pluto-on-binder. Perhaps some fusion of the two repos and simply processing the built HTML to point to a different binder than the one above would be sufficient to get this working.

[sethaxen]

@OriolAbril @ahartikainen I ended up going with a different approach. The Quickstart is still a Pluto notebook, but this is hidden from the reader of the docs, so we don't need to worry about Binder timing out if they try loading it as a notebook.

Instead of directly using Pluto, we use PlutoStaticHtml to build the notebook, which then emits Documenter-compatible markdown, so that the resulting built notebook integrates well into the documentation (i.e. not with an embedded iframe).

We still get a few benefits from the Quickstart being a notebook that make this worthwhile:

• Pluto now stores a package Manifest within the notebook, so that it's completely reproducible. This allows us to drop almost all of our documentation dependencies and prevents any of the notebook dependencies from influencing the rest of the docs build. That would be nice, but then the quickstart would only build with the actual version of ArviZ in the repo when tagging a new release on GitHub. So instead we'll forego Pluto's package management and use a docs environment whose compatibility can be managed by CompatHelper.
• We can access the quickstart as a notebook for interactive editing.
• Now that we have the infrastructure in place, we can add additional notebooks.

[sethaxen]

See the new build at https://arviz-devs.github.io/ArviZ.jl/previews/PR136/quickstart/

[OriolAbril]

I see a dark theme and can't find where to change it (it seems hardcoded to the browser theme). The xarray html looks a bit strange with that and is hard to read. Something similar happened to me with xarray-einstats docs. Not sure how much will be applicable to this case, in sphinx outputs get specific classes that I used to make the style more specific (and thus prioritary). Here is what I did: https://github.com/arviz-devs/xarray-einstats/blob/main/docs/source/_static/custom.css#L52.

[sethaxen]

I see a dark theme and can't find where to change it (it seems hardcoded to the browser theme).

It's the gear on the upper right.

The xarray html looks a bit strange with that and is hard to read.

Yes, there are two issues going on here. First, PlutoStaticHTML is adding margins that make the spacing not look great (see rikhuijzer/PlutoStaticHTML.jl#93). But second, the xarray CSS looks not great on dark mode. This is actually independent of anything in this PR, and its even worse when users are working in Pluto notebooks, where dark mode is tied to the OS theme.

Something similar happened to me with xarray-einstats docs. Not sure how much will be applicable to this case, in sphinx outputs get specific classes that I used to make the style more specific (and thus prioritary). Here is what I did: https://github.com/arviz-devs/xarray-einstats/blob/main/docs/source/_static/custom.css#L52.

Thanks, I'll look into it! Whatever the solution, it can't be specific to our docs, as it should also work for Pluto. I haven't prioritized fixing this so far, because as part of #128, we will eventually stop using xarrays HTML reprs.