Convert tutorials to Jupyter Notebooks

[brenthuisman]

• [ ] Convert tutorial pages to Jupyter Notebooks
• [ ] Remove associated examples, and convert them to .py to maintain having them checked by CI
  • When converting, don't add any Jupyter magics to the script as this will render the output script not a valid Python script.
• [ ] Question: where to host/make the notebook runnable?
  • Ebrains? Non-members can not access the Lab environment
  • Binder? Tutorials seem to fit in the resource limits. No account required. To be tested. Requires a file in our repo.
  • Some other options
  • Google Colab? Tested and works, good perf. Requires Google account.

[schmitts]

Please keep the tutorials and examples as pure Python files in addition. Maybe https://github.com/brian-team/brian2-binder/blob/master/generate_notebooks.py can serve as a blue print.

[akuesters]

Regarding EBRAINS: The point of source could be https://ebrains-cls-interactive.github.io/online-use-cases.html BUT: user needs access/account on EBRAINS

Jupyter-JSC could also be an alternative, BUT access the JSC resources is also needed.

[akuesters]

Regarding Linkage of docs and tutorials:

Option 1: Extract text and code from notebook to generate documentation. Option 2: Remove the tutorials from the docs, and refer to the dir with notebooks on Github. Github will render them and we can add a link in the notebooks that lets you execute them on binder etc.

For running the tests, we need to extract code from notebooks (nb-convert).

[akuesters]

Additionally to binder, we could have a look at voila as well to turn Jupyter notebooks into standalone web applications.

[schmitts]

Cf. https://github.com/electronicvisions/brainscales2-demos where sphinx documentation is converted to jupyter notebooks.

[akuesters]

Thanks for the link, Sebastian. From flying over it I could see that

• they use https://github.com/QuantEcon/sphinxcontrib-jupyter
• they execute the notebooks on EBRAINS.

[akuesters]

Comment from Padraig Gleeson in dev meet:

• The tool runipy works also for testing notebooks...Unfortunately unmaintained....
• This is how I was using runipy, testing that the notebook was valid and running with the current code: https://github.com/OpenSourceBrain/NWBShowcase/blob/master/.github/workflows/omv-ci.yml#L57
• I didn't want to convert/commit to an explicit script, just wanted to make sure the notebook was still valid without reloading and running manually.

[akuesters]

Lennart Landsmeer shares IO notebook on LFPy: https://github.com/llandsmeer/iopublic/blob/main/Local%20field%20potential%20v2.ipynb