Review and rendering of example notebooks for github rendering

[emiliom]

Review and current state

In PR #53 we ran into the limitations of GitHub Jupyter notebook previewing. Some of those limitations are well known and expected (eg, elements that involve interactive HTML or JavaScript will typically not be rendered), but others are unexpected and more severe (large blocks of cells are not displayed at all).

In that PR we also decided to try to include all 5 current notebooks in example_notebooks in a rendered form. That goal is outside the scope of PR #53 and will be tracked here.

• example_notebooks has 5 notebooks. 3 of those include Folium maps (echopro_workflow.ipynb, kriging_mesh_walkthrough.ipynb, transect_selection_workflow.ipynb), and the other 2 don't (bootstrapping_walkthrough.ipynb, semi_variogram_workflow.ipynb).
• echopro_workflow.ipynb and transect_selection_workflow.ipynb can readily leverage the new, optional plotting arguments in PR #53 that reduce or minimize the plotting of mesh point layers to keep notebook file size to a reasonable size (say, < 20 MB). kriging_mesh_walkthrough.ipynb will require more discussions

Apparently github notebook previewing is not just limited but also glitchy, such that things that worked one day may be broken the following day. I have a hunch that the missing block of cells may be one such glitch and is temporary. However, I also learned that what's encoded in the notebook when run and saved, and how it's then rendered by github, has some dependence on the conda environment used. I tested this via a couple of gists:

• Test 1 gist: echopro_workflow.ipynb executed with a conda env based on conda_install.yaml, followed by pip install -e .. All cells after the first Folium cell are not visible.
• Test 2 gist: Same notebook, but executed using a lighter-weight conda env intended to be run within JupyterLab. Note that the entire notebook is visible; interactive elements like Folium maps are not rendered, as expected.

Preliminary recommendation

While unrendered cell output is to be expected for interactive elements in the github preview, omitted cells (and especially large blocks of cells!) are problematic because the presentation of the notebooks could be very misleading. Trying to minimize this problem will probably take too much (ie, time consuming) fine tuning, and this may be a transient github problem to begin with.

I suggest we shift our energy towards deploying a very simple JupyterBook instead, where we can ensure the notebooks are nicely rendered. Then, the decision about whether to have rendered or unrendered notebooks in example_notebooks can be made independently. The JupyterBook would be the starting point for the eventual EchoPro documentation.

Notes

• See PR #53 for more detailed exchanges about github vs nbviewer rendering, etc.
• ipywidget elements are not showing up on nbviewer, either. Based on initial R&D, it's unclear to me if ipywidgets are expected to be rendered on nbviewer at this time (eg, there are discussions as far back as Sept. 2017 of ipywidgets that were rendered in nbviewer no longer did with a new release of ipywidgets). But ipywidgets will likely never show up on the github preview, so let's not worry about them at this time.

[emiliom]

Some of this was completed and included in release 0.3.0. Keeping the issue open, though, to track other topics discussed here.

[brandynlucca]

The current example workbook file supersedes this and can therefore be closed. Some of the points discussed here may be revived in the future.