feature: Storing Notebook examples without output, and better integrating them into the docs

[aleaf]

Is your feature request related to a problem? Please describe.
Right now, we are storing our Jupyter Notebook examples with the output committed, in a subfolder under examples/. There are a few issues with this:

• tracked output means each Notebook changes every time it is run. In addition to obscuring line contribution totals (which I have probably benefited from, hah!) it more importantly leads to merge conflicts. For example, I just had to wade through several dozen merge conflicts, none of which involved input, just to rebase a PR to the main. This is a barrier to potential developers, especially when it can take awhile to get PRs reviewed and merged.
• tracked output also means that output from individual's computers, including things like absolute file paths, are getting published in our docs.
• this is a bit more trivial, but this kind of setup also adds some extra friction for any users wanting to view the examples-- they have to click through a few different pages and then wait for the notebook to render, which can take several seconds and sometimes fails, etc.

Describe the solution you'd like
Other projects such as geopandas and xarray store their example notebooks in the docs folder, with no output committed. The notebooks are then rendered when the docs are built into something nice like this

Describe alternatives you've considered
There are probably a number of ways to do this. I haven't used the gallery functionality in nbsphinx (which I believe geopandas is using), but I do use nbsphinx in other projects. The general workflow I've used is

• having a general test module that executes all notebooks in an examples folder each time the tests are run, and also as part of the documentation build workflow
• after the notebooks are executed, nbsphinx renders them into html as part of the documentation

Open to ideas on how best to address this, and happy to help with whatever we decide on.

[wpbonelli]

Thanks @aleaf, removing notebook output and execution metadata from version control has been discussed but hadn't looked at specific solutions yet

Re: item 2, these two recent PRs should have scrubbed all the absolute paths from notebooks

MODFLOW 6 example notebooks are rendered nicely on ReadTheDocs, I think via a similar workflow to the one you describe, I could look into doing the same for FloPy notebooks.

[wpbonelli]

Re: removing notebook outputs from version control, it seems there are a few options:

• using git config and a .gitattributes file (related SO discussion)
  • pro: immediately compatible with nbsphinx
  • con: requires one-time setup for developers
• jupytext has a solution which pairs each notebook (.ipynb JSON file) with a regular .py (or Markdown) file, then automatically keeps both in sync — .py files can then be checked in and .ipynb files left out
  • also compatible with nbsphinx with extra configuration

Looks like the 2nd is currently used for tutorials, with jupytext run manually in rtd.yml CI workflow rather than by nbsphinx in the ReadTheDocs build

[aleaf]

Thinking about this some, it seems like the git config/.gitattributes route might be the best, as this would allow us to keep the Notebooks in their native format. Unless I'm missing something, it looks like we need to have the notebooks within the source/ folder for the documentation for nbsphinx to work. We could either

• move them there, similar to other projects such as Geopandas. A potential disadvantage of this is that they are buried in the docs folder. I think this route assumes that non-developers would primarily run the notebooks through Binder, which is maybe not a bad assumption. For example, Geopandas has links to binder within each notebook that is rendered in their docs. They then simply have a markdown file under examples/ (where I think their Notebooks used to be), with a link pointing users to the example gallery in the docs.
• an alternative would be to leave the notebooks in examples/ and then copy them on the fly as part of the doc building. This could be accomplished via a copy script referenced in conf.py. Maybe there are other ways as well.
  @langevin-usgs

[wpbonelli]

After thinking on this / using this more I am less sure notebooks should be kept in ipynb format as discussed here, here with possible advantages to keeping them as Python scripts managed by jupytext

• Similar to @aleaf above I imagine many users will either copy-paste code from RTD, or run the notebooks via Binder? If someone has cloned the repo and is using jupyter it doesn't seem burdensome to add an extra step (jupytext --from py --to ipynb <file>), which can be documented in RTD and in the dev docs. Also paired .py scripts may be more accessible as they are human readable and can be run with Python per usual
• After using option 1 above (jupyter nbconvert preprocessors in a custom git filter) for some time, it's a bit painful. It seems suitable for repos with a small number of fast notebooks, but the filter is currently slow. Even git status is slow as indexes are refreshed. I have also had to battle git to switch between branches, if notebooks are in different states on them (I found it easier to temporarily disable the filter in .gitattributes). Maybe I am doing something wrong and there is a simple solution.
• Metadata is a bit easier to add to scripts as instead of JSON at the bottom of the file it is YAML at the top. This could be used to group notebooks in sections and keep track of authorship (which can be lost to git/GitHub when notebooks are moved/renamed, branches merged, etc)

# ---
# jupyter
#   jupytext:
#     ...
#   kernelspec:
#     ..
#   metadata:
#     section: mf6
#     authors:
#       - name: ...
# ---

Tutorials are currently (and were before 1774) managed by jupytext, in any case doing both tutorials and examples the same way would allow a simpler docs build and less to remember, whether that is ipynbs or jupytext

edited

[christianlangevin]

Hey @w-bonelli, if we were to switch over to storing the content as py scripts instead of as ipynb notebooks, would there be a downloadable copy of the ipynb notebook available on RTD? I don't get the sense that there is a lot of binder use. I think a more common use case is that someone sees a potentially interesting notebook, they download it locally by clicking the file download button in a browser, and then they run and modify it locally. Based on your experience, it seems like there are a lot of advantages to swtiching over to py scripts and converting with jupytext, but it would be nice to keep the notebooks easily downloadable somehow, if possible.

[wpbonelli]

@langevin-usgs sphinx-gallery has download buttons, see for instance PyVista docs, but I don't know of a similar capability from nbsphinx (asked here). Understood re: binder (our config seems currently broken anyway) and I definitely see the benefit of providing an easy way to download notebooks.

[wpbonelli]

Completed by #1774 and #1794. Some notebook performance issues remain but maybe best addressed separately