[DOC] Improved walkthrough with GIFs

[tsalo]

Closes #690. Still a WIP.

https://tedana--765.org.readthedocs.build/en/765/multi-echo_walkthrough.html

The more I think about it, the more I wonder if maybe we should move things like the multi-echo walkthrough into a different location, like a Jupyter Book, with https://naturalistic-data.org as inspiration.

GIFs are going to take up a lot of space and bulk up our git repository, but I do think they're really helpful for learning about multi-echo fMRI.

Changes proposed in this pull request:

• Add gifs to help readers build a more intuitive understanding of multi-echo denoising.

[codecov]

Codecov Report

Merging #765 (797b026) into main (7e1cf2c) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     #765   +/-   ##
=======================================
  Coverage   93.19%   93.19%           
=======================================
  Files          27       27           
  Lines        2204     2204           
=======================================
  Hits         2054     2054           
  Misses        150      150           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7e1cf2c...797b026. Read the comment docs.

[eurunuela]

I agree that a Jupyter Book would fit the walkthrough much better.

GIFs are definitely useful to understand the content, but I wonder if a dash app or an Observable notebook would be nicer. Folks would get to "learn by playing" with interactive plots.

[emdupre]

I'd vote for "all of the above" if folks have time and interest !

Specifically on this point:

GIFs are going to take up a lot of space and bulk up our git repository, but I do think they're really helpful for learning about multi-echo fMRI.

Do we have to host the GIFs here ? Could we host them on e.g. OSF and just render them in the docs ? I've also successfully hosted animated SVGs as Gists in the past, which could be another option ?

[tsalo]

Would it be difficult to set up the Jupyter book in another repo and just let folks add to it as they're willing/able?

Could we host them on e.g. OSF and just render them in the docs ?

That seems feasible. I'll try it out.

[tsalo]

@emdupre this doesn't seem to be working. Any ideas?

My local docs build:

[emdupre]

I just requested access to that OSF link to see what it includes !

[emdupre]

I think you should modify to the "render" link, e.g.
https://mfr.osf.io/render?url=https://osf.io/mx4ku/?direct%26mode=render%26action=download%26mode=render

But updating the url as appropriate !

[tsalo]

Hm... it seems like it should work, but it doesn't seem to help:

[emdupre]

Here's what's happening and (at least) two suggestions.
During the build process, Sphinx is trying to copy the files into the generated _build directory. Because these are embedded images on a web page, this process fails and results in what you're showing above. To resolve this, we could (in no particular order) :

• Update those image tags to iframes, to embed the web pages
• Fetch the relevant files using cURL or the OSF API during the documentation build process so they would exist appropriately in the _build directory.
• Switch to another provider (or revert to GitHub) where we can access the files themselves.

Do you have a preference, @tsalo ?

[tsalo]

Thanks for digging into this.

Do you have a preference, @tsalo ?

I'm not sure. I'm leaning toward iframes for right now, but I also really want to try out the Jupyter Book idea, in which case the GIFs would be generated by, and rendered in, the notebooks.

[tsalo]

I'm just going to close this in favor of the Jupyter Book. If that doesn't work out for some reason, I can reopen this.