Modifications to use sphinx gallery for the tutorials.

[TeresiaOlsson]

This is an example for how to use sphinx gallery for the tutorials.

I think it looks very nice and gives both the option to download files and run them interactively with binder. It follows this: https://sphinx-gallery.github.io/stable/auto_examples/index.html

Downsides are:

• Some parts of the tutorials needs to use rst syntax instead of markdown.
• Sphinx gallery generates notebooks from python files. It can't use notebooks directly. So someone writing a tutorial need to first write the notebooks to test, then export to a py file and make some manual modifications to change markdown to rst.

However, py files are better for version control than notebooks.

It looks like this if you don't want to build locally or download the artifact from the workflow to be able to see it.

[GamelinAl]

A few issues:

• For interactive use, we will depend on a service provider. For example, at the time I write this binder does not work.
• This requires to learn a new way to make documentation (.py + .rst), to in the end, have a notebook like appearance.

Other than this, it can be a good idea. And for sure it's much better for version control to have .py files than .ipynb files.

[gubaidulinvadim]

A few issues:

* For interactive use, we will depend on a service provider. For example, at the time I write this binder does not work.

* This requires to learn a new way to make documentation (.py + .rst), to in the end, have a notebook like appearance.

Other than this, it can be a good idea. And for sure it's much better for version control to have .py files than .ipynb files.

I agree in general, but the notebook can always be downloaded even if Binder is down. I think the .py is just internal requirement. Any .ipynb can be converted into .py (with Spyder-like formatting).

[gubaidulinvadim]

@TeresiaOlsson It looks nice. I will finish this week the refurbishment for old complete example notebooks making them common to all facilities python-accelerator-middle-layer/pyaml#182

[TeresiaOlsson]

A few issues:

* For interactive use, we will depend on a service provider. For example, at the time I write this binder does not work.

* This requires to learn a new way to make documentation (.py + .rst), to in the end, have a notebook like appearance.

Other than this, it can be a good idea. And for sure it's much better for version control to have .py files than .ipynb files.

I'm also not so happy about the .py + .rst but there seems to be no way around it if we want to use sphinx gallery. It's annoying but I read in their issues that this is an intentional choice from their side. Other people had also complained.
Still, it is possible to also use .ipynb in the same documentation but it won't give an interactive notebook. Just a static page.

Do you think there is some option to have interactive notebooks without relying on a service provider? I was briefly pondering if we could use the jupyter hub + lab container setup our department maintains also to provide a test environment for pyAML users. During the last Bluesky workshop at DESY they used a kubernetes setup to spawn containers for everyone. It seemed quite easy to set up and was nice but we still need hardware, user management and likely some support when it goes down. So I gave up on that idea for now... But maybe binder is not the best provider?

[TeresiaOlsson]

I took a look at JupyterLite yesterday and I think it could work for us an an alternative for interactive notebooks without relying on a service provider. At least for some tutorials since it doesn't seem to easily support all type of packages. But I think it with sphinx gallery could be possible to have two buttons, one for JupyterLite and one for Binder and then the user can choose which one to go for depending on the needs.

But so far I haven't found any option that sounds like a reliable choice to me for how to directly write as a notebook and make it interactive. But maybe it will come in the future. It seems like a lot of people are asking for it in various issues, but they are also pointing out the problems with having .ipynb in version control.

So maybe for now we try the sphinx gallery approach and see how easy it is to write a notebook, export it and then manually do the tweaks to be compatible with sphinx gallery. It sounds like it should mostly be that people need to learn the differences between md and rst and manually translate that part. It's annoying but maybe anyway something necessary to learn since sphinx uses rst.

[gubaidulinvadim]

I took a look at JupyterLite yesterday and I think it could work for us an an alternative for interactive notebooks without relying on a service provider. At least for some tutorials since it doesn't seem to easily support all type of packages. But I think it with sphinx gallery could be possible to have two buttons, one for JupyterLite and one for Binder and then the user can choose which one to go for depending on the needs.

But so far I haven't found any option that sounds like a reliable choice to me for how to directly write as a notebook and make it interactive. But maybe it will come in the future. It seems like a lot of people are asking for it in various issues, but they are also pointing out the problems with having .ipynb in version control.

So maybe for now we try the sphinx gallery approach and see how easy it is to write a notebook, export it and then manually do the tweaks to be compatible with sphinx gallery. It sounds like it should mostly be that people need to learn the differences between md and rst and manually translate that part. It's annoying but maybe anyway something necessary to learn since sphinx uses rst.

For me it's completely acceptabel to have .py files + .rst. It's also better for version control. The problem with binder availability can be solved by having a "download notebook" button. I don't like to overcomplicate things too much and adding several providers, etc. It's a burden to maintain many different things at once.

[TeresiaOlsson]

I took a look at JupyterLite yesterday and I think it could work for us an an alternative for interactive notebooks without relying on a service provider. At least for some tutorials since it doesn't seem to easily support all type of packages. But I think it with sphinx gallery could be possible to have two buttons, one for JupyterLite and one for Binder and then the user can choose which one to go for depending on the needs.
But so far I haven't found any option that sounds like a reliable choice to me for how to directly write as a notebook and make it interactive. But maybe it will come in the future. It seems like a lot of people are asking for it in various issues, but they are also pointing out the problems with having .ipynb in version control.
So maybe for now we try the sphinx gallery approach and see how easy it is to write a notebook, export it and then manually do the tweaks to be compatible with sphinx gallery. It sounds like it should mostly be that people need to learn the differences between md and rst and manually translate that part. It's annoying but maybe anyway something necessary to learn since sphinx uses rst.

For me it's completely acceptabel to have .py files + .rst. It's also better for version control. The problem with binder availability can be solved by having a "download notebook" button. I don't like to overcomplicate things too much and adding several providers, etc. It's a burden to maintain many different things at once.

For me too. Actually I think the JupyterLite button was already there in the example I used to create this PR. I just removed it. But I can easily put it back if we want to try it. I think it was just a couple of lines in the config and that button also appears. But then we have to maintain that the notebooks actually run in that environment... Better probably to just start with binder + download button. I think downloading is anyway the best choice because that's the way to test that you have installed the environment correctly on your own computer.

I will merge this in.