Move tutorials to notebooks

[avan1235]

Closes #119

I prepared extra badges for each tutorial to load them automatically to nbviewer basing the configuration on the configs from lets-plot library examples.

We can run executable version of notebook just by single click on or browse it not in GitHub version by clicking on . The preview should also be loaded on GitHub in the same way but loading process fails sometimes and manual reload is needed. Btw I linked refs to totorials to nbviewer location of files in markdown as this seems to be more readable and stable but they are still accessible from GitHub (FYI the nbviewer and binder use only files stored on repository so all files are kept only in repository).

For now, all refs are created to point to my fork, I will change it before merge to master to make it working for now (as there are no notebooks in master KotlinDL branch that the badges should point to). The change includes changing avan1235 to JetBrains and notebooks to master.

I encourage you to do the review by starting from the main README.md on my fork, the nbviewer version of quickstart guide or just from the docs directory from my fork if you wish to use bare GitHub.

The changes includes some small changes in notebooks code to make it working and more readable in my opinion so feel free to comment with your opinion.

[zaleslaw]

First of all, it's really great and more interactive way to have and run tutorials. Thanks for that implementation.

My user experience:

1. Binder initialization is slow (maybe we need to add in Readme. md) some docs about its architecture, running docker, loading software
2. Nbviewer integration is good and works
3. Github displays notebooks really bad
4. I could not read tutorials as plain text to copy some code in my idea on Github. I need to go nbviewer
5. Summary method in notebooks is ugly

It improves user experience, of course, let's think about contributors:

1. The content in notebooks is not equal to the code/text in the /docs folder. It's not easy to review
2. Contributing and fixing typos in markdown files is easier than in notebooks
3. What if we need different software (for example, different TF or Keras versions)? Could we set it differently for different notebooks?

I suggest splitting your improvements into a few parts for easier reviewing:

1. Fix some things in the code of tutorials (also, it could be adopted in examples too)
2. Propose changes in the text (probably I will need to ask for a review from our copy-editors, they do the same for the current version of tutorials)
3. Convert the content to notebooks (or copy content to the notebooks) with minor changes related to the notebooks (let's plot support, different summary method, and so on).

At this point, I think that we need to keep both, plain md tutorials (for IDEA users) and notebooks

[avan1235]

First of all, it's really great and more interactive way to have and run tutorials. Thanks for that implementation.

My user experience:

1. Binder initialization is slow (maybe we need to add in Readme. md) some docs about its architecture, running docker, loading software

It's slow only on the first run of the environment as I have read here

2. Nbviewer integration is good and works

3. Github displays notebooks really bad

Yeah I saw this problem but hope that it is a matter of some time when it becomes more and more popular and GitHub fixes some bugs.

4. I could not read tutorials as plain text to copy some code in my idea on Github. I need to go nbviewer

They shouldn't be visible as plain text, I supposed GitHub will render them properly as notebooks every time and then from these notebooks we should be able to copy code/text.

5. Summary method in notebooks is ugly

That's why I created an issue #135 (one of them as there are more)

It improves user experience, of course, let's think about contributors:

1. The content in notebooks is not equal to the code/text in the `/docs` folder. It's not easy to review

I haven't thought about review time but it is possible to review the GitHub PR in IntelliJ and when working with notebooks we should use another plugin in IntelliJ for jupyter notebooks - then they are readable and editable like in nbviewer or datalore.

2. Contributing and fixing typos in markdown files is easier than in notebooks

Yes, the plugin for IntelliJ would be required but it seems that then everybody could contribude as it looks then as Markdown files

3. What if we need different software (for example, different TF or Keras versions)? Could we set it differently for different notebooks?

Now it is not possible. We can find the official discussion here

I suggest splitting your improvements into a few parts for easier reviewing:

1. Fix some things in the code of tutorials (also, it could be adopted in examples too)

2. Propose changes in the text (probably I will need to ask for a review from our copy-editors, they do the same for the current version of tutorials)

3. Convert the content to notebooks (or copy content to the notebooks) with minor changes related to the notebooks (let's plot support, different summary method, and so on).

May be a little bit annoying copy-paste work as Markdown files had some lines wrapped and will be hard to recoever/spot differences. I will try to work on it in this way but reversing the changes to Markdown now seems to me as unneeded work.

At this point, I think that we need to keep both, plain md tutorials (for IDEA users) and notebooks

Let's try the IDEA plugin for jupyter notebooks.

P.S. I just realised that there is no plugin for Jupyter but rather an Ultimate version of IDEA. That's not the best approach btw so maybe some extra reasearch would be needed if we really would like to use notebooks?

[zaleslaw]

Thanks for the good and clear comments on my questions, dear @avan1235 so, I need to think about it more and discuss it with colleagues, so after vacation let's revisit this PR and define the next steps regarding the notebooks.

I will share with you later yet one approach of building tutorials from kotlinx.serialisation and multik projects based on tests/text preprocessing and markdown (but looks like your approach is better)

[avan1235]

Ok, I hope to get to know some other approaches, maybe we will find the most suitable here. Btw I will try to create a separate PR with some changes for now for .md tutorial and examples as I think this PR can take longer time in such scenario 😉