Chapter 2

[kvenkman]

The PR primarily contains a python file created using jupytext from a notebook. It would be good for someone to take a look, see if it converts back into a notebook nicely, and is executable all the way through.

The PR also contains an updated environment.yml file to include a few new dependencies.

[dhavide]

@kvenkman , I have set up the environment with jupytext on my own MacBook machine. Some notes to consider:

• The environment in the file environment.yml did not build directly for me; the conda solver could not build the environment directly on my machine. I used git diff to compare the file against the original environment.yml to see that three packages needed to be added. I rebuilt the original environment and added the three packages one-by-one with conda install. Weirdly, this built the desired environment without breaking the conda solver. This is a strange behavior for conda, but it shouldn't concern us if we want to encourage using showcase.2i2c.cloud.

• The round-trip conversion between .py to .ipynb formats worked successfully, i.e., I was able to generate the notebook, execute its content & convert the notebook back to a . However, we need to test this out with a notebook that uses more MarkDown formatting (e.g., section headings, hyperlinks, etc.) to make sure that no information is lost in translation. It would be annoying for someone to work on formatting a notebook and lose their time when converting to a different format. We should remember to address this (I'll construct an issue). This also raises the question of whether Markdown (.md) files should be used as the source format for checking results into the repository rather than Python (.py) files. I have a slight preference for Markdown in that we can see the formatting directly. Part of that decision needs to be made based on any constraints of JupyterBook, i.e., are there .md/.ipynb peculiarities that we need to observe/preserve that don't play well with jupytext?

• If we have an intended workflow for developers, we should document that somewhere. That is, if the intention is to check only .py files into the repository and to use jupytext to generate .md and .ipynb versions of relevant files, a file (say, CONTRIBUTING.md) should describe this process for the benefit of other contributors. Again, this is something that warrants an issue.

• Similarly, if the intention is that one format (.md or .py) will constitute the "ground truth" for materials in the repo, then we should add a .gitignore that blocks other generated file formats from being suggested as additions to the repo.

[kvenkman]

Hi @dhavide ! You raise great points. I'll see what the issue is with the environment.yml. I'm also running into some reproducibility issues at my end with rasterio being unable to read datasets stored in the cloud, which I suspect to be a version issue with one of the underlying packages. I'll investigate and fix this.

Agreed on your third and fourth points - I'll modify the .gitignore and raise a PR. Let's discuss the write up of a Contributing.md document.