DanPuzzuoli
commented
1 year ago Hi - we originally had the tutorials as jupyter notebooks but switched torst files (which are built with sphinx) for a couple of reasons:
- This way they are just like any other documentation, and so the code in the tutorials is run every time the documentation is built, including in the tests that are required to pass for every PR. This means that we always know that the tutorials are working in a standardized environment, so we don't accidentally break a tutorial without knowing.
- Jupyter notebooks aren't great when it comes to tracking changes. Every time it is re-executed by someone, even with a very minor change, it can look like a large number of changes were made to the file.
For these reasons we won't be switching back to .ipynb files for tutorials, or directly including them in this repo. That being said I generally agree with the sentiment that it would be nice to have them available in some way. nbconvert offers tools for converting between formats. We used it in the original conversion from .ipynb to .rst. I haven't tried to go the other direction, but if it works well it's not a bad idea to add a description of how to do this to the readme.
NeoFantom
What is the expected behavior?
A jupyter notebook tutorial would be better and more useful.
Currently the tutorials are rst files. I don't know how to build them locally. If this can be done, it should be written in the readme. Or it is better if you can provide a .ipynb tutorial, which we can simply clone and run locally.