Experiment with moving tutorials under docs/source/notebooks

[aterzis-google]

To get an idea, compare:

https://github.com/google/objax/blob/master/docs/source/notebooks/Logistic_Regression.ipynb

with

https://objax.readthedocs.io/en/latest/notebooks/Logistic_Regression.html

[david-berthelot]

Also: is having both in github and notebooks an option?

[aterzis-google]

Yes, it's possible to have the tutorials in both readthedocs and github but to do so we will need to move them under docs/source/notebooks (or have two copies which is undesirable)

[AlexeyKurakin]

I think all of the notebooks are shown on github, either under https://github.com/google/objax/tree/master/examples/tutorial or https://github.com/google/objax/tree/master/docs/source/notebooks

Also any ipynb files from github could be opened in google colab by using https://colab.sandbox.google.com/github/google/objax/blob/master/PATH_TO_FILE url. Here is metric-learning.ipynb in colab

However if we want to be able to render notebooks on readthedocs, then they have to be within docs/source directory subtree. Does not have to be in docs/source/notebooks, but have to be within docs/source subtree.

[AlexeyKurakin]

So if we want to keep these additional notebooks in examples\tutorials and just have a link to colab in readthedocs.io we can just edit links in docs/source/tutorials.rst to point to google colab. Or show two links, one points to colab, another one points to github page.

All my comments above just to emphasize that location of the ipynb files only affect whether they rendered in readthedocs. And it does not affect whether it could be shown in colab.

So I think it gets down to following questions:

1. Do we want certain notebooks to be rendered in readthedocsio?
2. What are the benefits of having notebooks in examples/tutorials? Is it easier for users to discover?
3. Do we actually want to separate examples/tutorials from docs/source/notebooks? In particularly, right now all notebooks from docs/source/notebooks are reviewed by many people and polished, while it's not the case for those from examples/tutorials
4. Does it make sense to a directory with notebooks in examples? Would user rather prefer to have *.py file to run?

[AlexeyKurakin]

I personally torn between following considerations:

• We should have some logical separation between well polished tutorials (like those from docs/source/notebooks ) and other contributed tutorials which were not as polished
• I think content of examples/tutorials is easier to discover by users who looking through examples
• I have a feeling that it's genearlly better to have *.py files in examples

Given all of the above, I think maybe we keep examples/tutorials as is, however we modify https://github.com/google/objax/blob/master/docs/source/tutorials.rst to have a link to open these tutorials in colab. And reconsider it if we have any other feedback from users

[aterzis-google]

@AlexeyKurakin thank you for thinking about this and thanks for the pointer on how to have colab automatically open the tutorials.

I like your suggestion. If everyone else agrees then I will abandon this PR, which moves the two files, and send another one that just updates tutorial.rst

[david-berthelot]

I also agree.

[AlexeyKurakin]

Seems like everybody agreed on update of tutorial.rst, so closing this pull request.