Should the landing page of the documentation point to stable or latest?

[h-mayorquin]

This was raised by @JoeZiminski on #2763 and I think is worth discussing.

A general question, is the 'latest' docs the ones built from main? I always thought that these were the latest release. To me it seems more intuitive to have 'latest' point to the documentation for the latest released version (100.6) and the docs built from main to be 'Development Branch' or something.

I would guess the main-branch docs are going to be relevant for relatively few people and there is an underlying assumption the docs are targetted towards users rather than developers (i.e. 'latest' is latest from a user perspective not a developer). What do people think?

[zm711]

I think it is a fair point overall. The docs in general should be for the user. So we should probably point them to the release. Although we still very often tell users to install from source due to the rapid development that is happening. So that would be my only reservation.

[h-mayorquin]

I tried to look for how to do this and I could not find the option so maybe the point is moot.

[zm711]

https://docs.readthedocs.io/en/stable/versions.html

It looks like there should be an option based on readthedocs. Looks like you have to put where your default redirect should go to. But they don't clearly describe how, just that you can do it.... (bottom of page)

[h-mayorquin]

Yes, that's how it looks. Maybe something to do disucss and do quickly in the coming hackaton.

[JoeZiminski]

Thanks both for looking further into this. I didn't realise that it is the intended design of read the docs :( Maybe in this case, as diverging from this standard would itself be confusing in itself for others, the solution could be to add some documentation on the 'Getting Started' page. We could have a brief block of text above the links to articles, suggesting generally how to get started with SI (e.g. do the getting started tutorial, ask questions at github issues or slack (?)), and also quickly explaining how the docs version work. That way most users should realise this is the design early on.

[h-mayorquin]

Yeah, that's the default. But I don't think is common practice among libraries of the scientiifc stack:
https://numpy.org/doc/stable/
https://docs.scipy.org/doc/scipy/
https://scikit-learn.org/stable/

[JoeZiminski]

Good point! Glad there is consensus (as a side note, I can't believe how nice the scitkit-learn docs are).

Randomly found this article that suggests a way to do it. It sets default version to stable and also renders a warning on the latest docs version that it is a dev version. However it is dated 2019 so maybe out of date, but worth a try?

[zm711]

I think you separately have to be an admin at rtd for a project. I don't think I have admin privileges so maybe we would need to loop in @alejoe91 unless you have rtd admin @h-mayorquin?

[h-mayorquin]

No, I don't have admin rights, that's why I suggested doing this quickly with Alessio and Sam in the hackaton.

[zm711]

Sorry I missed that. sounds good to me!

[h-mayorquin]

No, I did not explain my reasoning for doing it on person on hackaton above : )