Update QC colab example in pylossless/notebooks

[scott-huberty]

Looks like this notebook needs to be updated.

I think it should be moved to docs/examples so that it can be automatically generated on the site (this would also make the generated notebook downloadable).

Unless there's some special github collab feature that I'm not aware of that automatically accesses [project]/notebooks

[christian-oreilly]

This issue is not about the QC colab example in particular, but the whole notebook folder. I have no objections about moving the content of ./notebooks to ./docs/examples.

[scott-huberty]

Awesome! Since you have had your hands on the jupyter_dash stuff, let me know if you have time to update the notebook.

[christian-oreilly]

Sure. I can do that.

[christian-oreilly]

@scott-huberty I am not convinced about your idea of putting this notebook it docs/examples. The examples there are .py files formatted so that they can be rendered as webpages. This is a Jupyter Notebook, which is meant to remain as such. I could move it under docs/examples or docs/notebooks, but either way it will not address your objective of having this automatically generated on the readthedoc site. The only way that this could be done is by transforming this notebook into a .py file, which breaks the hook to Colab because this hooks works for Jupyter notebooks stored on GitHub, not .py file transformed into .ipynb by sphynx (or whatever other tools that is responsible for this automation) for download from readthedoc.

[christian-oreilly]

The example is fixed now (in the corresponding branch). I'll wait for you to comment on integration with the website and DevOps before merging it as a PR.

[scott-huberty]

which breaks the hook to Colab because this hooks works for Jupyter notebooks

I'm not familiar with this "colab hook" you mention. What's the purpose of it?

This is a Jupyter Notebook, which is meant to remain as such.

I'm pretty sure You can specify during build to actually run the .py file and generate the output on the webpage. Then at the end of the page, the user can also download the example as a jupyter notebook file. For example this is how MNE generates their tutorials.

I'm not 100% sure if this works with Dash. I can look into it.

[scott-huberty]

Example: https://mne.tools/stable/auto_tutorials/raw/20_event_arrays.html

(In our only current tutorial, I intentionally did not run that notebook when building, because that tutorial is broken and the build would fail).

For the record yes it is a .py file, but you add # %% markers to specify that the code in the file should be treated as a Jupyter notebook. (Specifically, it is used to divide the code in your file into separate cells, just like you would in a Jupyter notebook)

[christian-oreilly]

You missed the point; this file needs to be on GitHub as a .ipynb, not be generated from a .py file. Every .ipynb file on GitHub has a corresponding URL on Colab, so for any .ipynb files on a github repo, you can provide a Colab URL that will launch that file automatically on Colab.

[christian-oreilly]

If, e.g., sphynx + readthedoc can not only generate a .ipynb from a .py file, but also make it accessible through Colab and provide a URL for it, then it works... else I does not.

[scott-huberty]

Every .ipynb file on GitHub has a corresponding URL on Colab, so for any .ipynb files on a github repo, you can provide a Colab URL that will launch that file automatically on Colab.

Yeah this is the part that I don't understand! How does one "launch" this in colab?

[scott-huberty]

You missed the point

I think the point I am not seeing is why a notebook version of this needs to live in this github repository / package?

[christian-oreilly]

I think the point I am not seeing is why a notebook version of this needs to live in this github repository / package?

So that it can be started automatically via Colab.