Docs issue: paths/links differ between Sphinx/RTD and local/Github rendering, leading to broken links

[sshanbhag]

Please fill in the following for any issues

Your setup:

1. Operating System (Linux, MacOS, Windows): MacOS
2. Hardware type (x86, ARM..) and RAM: x86, 16GB
3. Python Version (e.g. 3.9): 3.11.7
4. Caiman version (e.g. 1.9.12): 1.10.2
5. Which demo exhibits the problem (if applicable):
6. How you installed Caiman (pure conda, conda + compile, colab, ..): conda
7. Details:

Wanted to let you know that the link in the documentation for setting up GPU use is broken. https://caiman.readthedocs.io/en/latest/README-GPU.md results in a 404 not found error:

404 Not Found

You are browsing the documentation of caiman. The documentation page you are looking for was not found.

Documentation changes over time and pages are moved around. You can try to navigate to the index page of the project and use its navigation, or search for a similar page.

[kushalkolar]

caiman doesn't use the GPU, there was a GPU implementation of NoRMCorre years ago but it's not worth looking into.

If you want GPU accelerated NoRMCorre look at jnormcorre which is mentioend in the Related Repositories section of the readme.

[EricThomson]

@sshanbhag thanks a lot for pointing out the broken link ( https://github.com/flatironinstitute/CaImAn/blob/main/docs/README-GPU.md ).

Indeed there also a second broken link at the bottom of the installation docs that links to the cluster docs!

While as @kushalkolar pointed out caiman currently uses CPU more than GPU-hungry algorithms, we should fix these links for people that want to explore this functionality.

[kushalkolar]

I'm pretty sure it depends on sk-cuda which is very ancient at this point and really not worth even trying.

If you want gpu accelerate normcorre it's worth looking at the jax implementation

[EricThomson]

Yes, for motion correction we are basically looking at legacy docs.

You might be able to get it working if you work really hard, but from what I've heard the payoff was negligible at best, so it was never really used. For the component evaluation with the CNN the GPU might be useful, but I haven't profiled how big of a bump this gives you.

At any rate, it's good to know about broken links, so thanks for the heads up @sshanbhag ! 😄

[pgunn]

The issue is that Sphinx/RTD and local/Github renders of the docs use different naming/serving conventions, making having good links between pages difficult.

Compare: https://github.com/flatironinstitute/CaImAn/blob/main/docs/source/Installation.rst to: https://caiman.readthedocs.io/en/latest/Installation.html

Same doc, same source, but the former's links work and the latter's do not (as the source docs were written with github rendering in mind). Also, some docs have dramatically different names on RTD (README.md -> index.html)

I'm looking at a few ways to fix this; two separate approaches we could try: 1) It may be possible to do some link rewriting in the sphinx-build process 2) We could also decide to just use sphinx/RTD for the things we need it for (function doc generation) and have people who want other kinds of docs to use the README and other things on Github (although this would go against the general hope that people can use Caiman without using the Githhub repo where they'd be wrongly tempted to clone the repo)

There may be other options. Either way this has been broken for awhile and it'd be good to fix it .

[sshanbhag]

Thanks for the info re: GPU. Just starting out with the software as we work with some new 1-P miniscope data. I had clicked on the link to see what needed to be done to use the GPU with CaImAn and whether it was useful or not... I have my answer and more! Cheers, Sharad

[EricThomson]

Ah, good to know: the CNN evaluation step is not used for 1p data 😄

[pgunn]

This is fixed on the dev branch and with our next release will be reflected on RTD.