Display Jupyter Notebooks

[kabilar]

• Fix Include notebooks into handbook? #142
• Using mkdocs-jupyter, display select Jupyter Notebooks from the dandi/example-notebooks repo
• Add manual trigger (i.e. workflow_dispatch) so that docs can be redeployed when example-notebooks are updated
• Fix GitHub Action: Add linux-headers package mhausenblas/mkdocs-deploy-gh-pages#256
• Preview available at: https://kabilar.github.io/handbook/
• In the future, we can add titles to all the notebooks as some just start with code blocks

[yarikoptic]

This is great, thank you @kabilar for taking care about this one!

• do you see a way to add some kind of "header" or "trailer" (or both) to each notebook so we could point to the to the original notebook location on github, and possibly state something like

This Jupyter notebook is available from GitHub repository dandi / example-notebooks / demos / NWBWidget-demo.ipynb. You can also find it available while working on DANDI Hub under ... so you could run the code.

hub seems to be down ATM so couldn't double check where it is there on the hub. Also might be worth adding a link to the corresponding dandiset DLP if it is associated with a dandiset, e.g.

This notebook accompanies dandiset 000XXX.

or alike.

• could we generate/include a page with an index of all notebooks by their filename (so not yet going deep into fixing to get the titles etc) so their all content gets rendered indexed? Crude listing/page generation script

❯ { echo "## Full list of example-notebooks"; find -iname '*.ipynb' | grep -v '\.ipynb_checkpoint' | sort | while read -r l; do echo "- [$l]($l)"; done } | head
## Full list of example-notebooks
- [./000004/RutishauserLab/000004_demo_analysis.ipynb](./000004/RutishauserLab/000004_demo_analysis.ipynb)
- [./000005/DataJoint/DJ-NWB-Yu-Gutnisky-2016/notebooks/Yu-Gutnisky-2016-examples.ipynb](./000005/DataJoint/DJ-NWB-Yu-Gutnisky-2016/notebooks/Yu-Gutnisky-2016-examples.ipynb)
- [./000006/DataJoint/DJ-NWB-Economo-2018/notebooks/Economo-2018-examples.ipynb](./000006/DataJoint/DJ-NWB-Economo-2018/notebooks/Economo-2018-examples.ipynb)
- [./000007/DataJoint/DJ-NWB-Gao-2018/notebooks/erd.ipynb](./000007/DataJoint/DJ-NWB-Gao-2018/notebooks/erd.ipynb)
- [./000007/DataJoint/DJ-NWB-Gao-2018/notebooks/Gao-2018-examples.ipynb](./000007/DataJoint/DJ-NWB-Gao-2018/notebooks/Gao-2018-examples.ipynb)
- [./000009/DataJoint/DJ-NWB-Guo-Inagaki-2017/notebooks/Guo-Inagaki-2017-examples.ipynb](./000009/DataJoint/DJ-NWB-Guo-Inagaki-2017/notebooks/Guo-Inagaki-2017-examples.ipynb)
- [./000009/DataJoint/DJ-NWB-Guo-Inagaki-2017/notebooks/Guo-Inagaki-2017-NWB-examples.ipynb](./000009/DataJoint/DJ-NWB-Guo-Inagaki-2017/notebooks/Guo-Inagaki-2017-NWB-examples.ipynb)
- [./000010/DataJoint/DJ-NWB-Li-2015b/notebooks/Li-2015b-examples.ipynb](./000010/DataJoint/DJ-NWB-Li-2015b/notebooks/Li-2015b-examples.ipynb)
- [./000010/DataJoint/DJ-NWB-Li-2015b/notebooks/Schemas.ipynb](./000010/DataJoint/DJ-NWB-Li-2015b/notebooks/Schemas.ipynb)

a better version could group them neatly under "Dandiset demos", etc

[yarikoptic]

Why not just to include them as a git submodule? that would disambiguate which version we are to render/include (e.g. we might want to avoid some recent one for some reason etc).

cons:

• would require "explicit" commit to update to new version, but "explicit is better than implicit", so could indeed still be a github workflow which would do that

WDYT?

[bendichter]

I actually prefer this. We use submodules in PyNWB and it's been a headache requiring special clone syntax. This is simpler and easier.

[kabilar]

Its been a while since I have used submodules so happy to look into it. I filed an issue (#148) to perhaps expedite this pull request.

[yarikoptic]

it is quite easy really, let me know if you need a hand with that.

It is just that without using them we would get "fluctuating" results of the doc build - it would depend on current version which has its pluses and minuses:

• +: we would always be "up to date" with notebooks repo since we would always use current master
• -: as a result we might get sporadic docs build failures if something in current state of notebooks would trigger failing their rendering/inclusion
  • and it would require then adjusting build script to point to specific commit etc making it "hidden"

but in either of the cases, in the long run we better also trigger rebuilding of the handbook whenever notebooks collection change.

• without git submodule -- it would be matter of just triggering rebuild workflow
• with git submodule -- it would require PR or at least a commit to update the state of the submodule.

So overall, let's may be proceed without submodules and see where we end up ;-)

[yarikoptic]

if included as submodule, would remove duplication of URL spec/action to get it here ...

[bendichter]

I think it might make more sense to render the notebooks on the example-notebooks CI and link to them rather than cloning that repo and rendering them here.