Using Examples folder is not easy to follow

[panjacek]

https://github.com/Urban-Analytics-Technology-Platform/od2net/blob/main/docs/tutorial_examples.md tutorial is bit confusing and python scripts are actually expecting a lot of harness to actually work.

1. I think it might be useful to create another image using builder stage of Dockerfile which would serve as examples "compiler"
2. README.md in examples folder would be easier to follow than a link to url to docs hidden in echo.sh
3. Simple Makefile with targets like build_docker / build_examples / test would be very helpful for newcomers to fast start
4. using symlink utils.py is not great, this folder should have a python pkg structure so proper importing would work.
5. autoformat and lint code with ruff.

[dabreegster]

Thanks for the detailed feedback and list of suggestions! All of these sound great to me.

I think it might be useful to create another image using builder stage of Dockerfile which would serve as examples "compiler"

Maybe this could then replace or simplify #76? Including all the external tools that're useful for generating inputs in one place sounds helpful for sure.

using symlink utils.py is not great, this folder should have a python pkg structure so proper importing would work.

I tried setting this up before, but I got stuck because the order of directories is inverted. Rather than the python main files living in dir1 and the common library also living in dir1 (or nested beneath), we've got examples in a bunch of subdirectories. I didn't spend that much time searching around to find the right structure, though. Do you know what's appropriate here?

[Robinlovelace]

+1 to simplifying things. Also an ask for making it easy for people to contribute from other languages, e.g. R or Julia, with a nod to upcoming SDSL conference next week: https://spatial-data-science.github.io/2024/