Skip to content

[T,nb,ci] Add support for markdown-based notebooks via jupytext

Lars Bilke requested to merge bilke/ogs:jupytext into master
  • Prove of concept for markdown-based notebooks via jupytext.

  • Example conversion of Linear_Disc_with_hole-notebook (web preview here).

  • Adds button to launch the notebook in BinderHub. Works with newly created MR notebooks too (see web preview above)! CleanShot_2023-03-01_at_10.44.22_2x

    • The BinderHub config is here: https://github.com/bilke/binder-ogs-requirements (may migrate this to GitLab ogs-group later)
    • When clicking the link it launches a Jupyter Lab instance pre-configured with ogs via wheel, clones the current ogs repo in it and opens the respective notebook ready to run. Please note that startup times may be several minutes and the computing resources are limited (1 core, 2GB RAM). For improved performance we would need to setup own infrastructure. Also currently only works for serial ogs configs.
  • notebook file parameter in Notebook meta data is now computed automatically @chleh.

  • Some ipynb notebooks needed to be converted to newer format (nbformat 4.5).


General consequences of using Markdown-based notebooks based on jupytext:

  • Edit notebook just with a text editor
  • Better git diffs, easier MR reviews
  • If Jupyter Lab configured properly then transparent usage:
    • Double-click on a markdown file will open it as a Notebook
    • Upon saving or executing a linked .ipynb-file is created in the background which stores outputs
    • You still edit the Markdown file but don't notice the difference to regular notebooks in the Lab UI
  • If OGS_USE_PIP=ON you get a properly configured environment in [build-dir]/.venv. Simply activate it and start jupyter lab.

  1. Feature description was added to the changelog
  2. Tests covering your feature were added?

Follow-up TODOS:

  • Any new feature or behavior change was documented? There will be a subsequent MR unifying existing notebook docs and showing usage, !4512 (merged)
  • Converting existing notebooks to markdown
  • Disallowing .ipynb-files in the repo.
Edited by Lars Bilke

Merge request reports