Interactive demo for jsonschema code examples

[martinzugnoni]

Hello @Julian,

I've been using jsonschema for a while and I really like what you've built. We are also using it to teach our students at https://rmotr.com/ (co-founder and teacher here) to work with RESTful APIs.

While looking at the code examples in the README file I thought it would be great to provide some interactive demo that people can use to play with the library before committing to download and install it locally.

A demo is worth a thousand words 😉

I spent a few minutes compiling jsonschema examples into a Jupyter Notebook file, and adapted it in a way that we can open it with a small service we have at RMOTR to launch Jupyter environments online. No account or subscription required to use it, so it's pretty convenient for people that wants to get hands on the library with a low entrance barrier.

The result is what you can see in my fork of the repo (see the new "Demo" section):
https://github.com/martinzugnoni/jsonschema

Do you agree that having such interactive demo would help people to know and use jsonschema?
Let's use this issue as a kick off to start a discussion. Nothing here is written in stone and we can change everything as you wish.

I hope you like it, and I truly appreciate any feedback.

thanks.

[Julian]

Looks great! Thanks!

Will leave a few comments soon as I get a moment this week but overall definitely seems reasonable to add in.

Appreciated!

[martinzugnoni]

thanks @Julian, absolutely!

No hurries at all. Let me know if there's something we should change. As I've mentioned above, this is just an initial version to start the discussion.

Appreciate your feedback.

[martinzugnoni]

@Julian did you have any time to take a look at Notebooks? If you confirm me I can move forward and create a PR with the required changes for the integration (shouldn't be much). Then we can iterate from there, either tuning the DEMO notebook or adding more code snippets. What do you think?

[Julian]

Hello! Apologies for the delay here... I did in fact take a quick look, and I had 2 main areas of concern pretty much --

First one is easy bikeshedding :), which is I just would like to slightly stylize the button a bit more so it fits within the text, as is it's a bit jarring / large :D

The second one is more important, which is that it worries me a bit to maintain the contents of the interactive demo as an ipynb -- it's very hard to review (changes) that way, even the current branch is hard to review without rendering the notebook essentially. I don't suppose you know whether there's a more data-driven way of defining the contents of cells? Say e.g. by defining a JSON file with the contents of each of the cells and then telling jupyter to use that? As is yeah, bit concerning maintainability-wise. But thoughts welcome!

[Julian]

(Another way by the way of maybe solving the first bikeshed there might be to instead use a clickable screen recording that leads you to the demo? But yeah something just looks off visually to me with the way the button is right now)

[martinzugnoni]

@Julian, it's my time now to apology for the delay response. Answering your concerns below:

1. Button style must definitely change. This is just an example, and we should find something that we can smoothly integrate in the README.

2. Sadly Github doesn't implement a Notebook diff (yet), but there are some libraries implemented for it, like https://nbdime.readthedocs.io/. I guess Github will integrate something like this in the UI soon, as Notebooks are becoming very popular. In the meantime, we can run the diff locally and review based on that.

If you confirm me I can move forward and create a PR and we can iterate from there.

[Julian]

:) no worries, life is life.

2. Sadly Github doesn't implement a Notebook diff (yet), but there are some libraries implemented for it, like https://nbdime.readthedocs.io/. I guess Github will integrate something like this in the UI soon, as Notebooks are becoming very popular. In the meantime, we can run the diff locally and review based on that

So I actually don't care much about GitHub to be honest, I don't use it to actually do anything really other than host the code and issue tracker, I review diffs in git outside of the website, it's just hard to review those changes as is because they embed things like ANSI color sequences in them, and a bunch of metadata... But yeah maybe that tool or another can get me the last mile there, it's not terrible, certainly not if it's an incremental change to the notebook I guess.

So yeah happy to see a PR!