Unversioned (permanent) home page

[melissawm]

📚 New content request

During today's Documentation working group meeting we have discussed using a permanent, unversioned home page to avoid versioning issues.

Outline

Can be done together with napari/napari#4275

[jni]

As a reference, here is the source of the mpl home page:

https://github.com/matplotlib/mpl-brochure-site

[Czaki]

Contribution instructions maybe also should be stable napari/napari#5581

[psobolewskiPhD]

The docs contribution instructions should also have dev as stable I think, see:
#145 and connected napari issue
napari/napari#5789

[melissawm]

Here's my current thinking around this:

• The low-effort solution is to just use the current workflow and infrastructure. Now, we redirect napari/napari.github.io's index.html to napari.org/stable/index.html; we could redirect to napari.org/dev/index.html, which will always be up-to-date (since it is deploying from main at every merge). (All of this also applied to the development docs btw, as we use the same redirecting to stable, but could redirect to dev).
• The slightly more costly solution would be to have another repo, with another workflow, similar to matplotlib/mpl-brochure-site. This would deploy independently to napari.github.io

I would lean towards the first solution because it prevents yet another repo, but I am open to discussion because there may be issues that I am not fully aware of.

[jni]

@melissawm I don't like option 1 because it causes visitors to be on dev for all docs. If they just go to napari.org they would land in the dev docs and see documentation for features that don't exist in their installation yet.

I think there might be an intermediate solution here, which is to have a whitelist of unversioned pages, and a script that at deploy time copies them from dev to stable. This would all happen on this repo. What do you think?

[melissawm]

Yup, that is certainly an option. Let me put up a draft and we'll figure out the details. Thanks!

[melissawm]

Ok folks - I have been trying to figure this out for a while and here's the long and short of it.

I can currently see 4 options for this (there may very well be another solution that I'm just not seeing!):

1. Copying over latest version of pages on top of previous versions. This is Unversioned pages: overwrite home and developer docs on stable with dev version #230
   • Pros: We don't need to touch any javascript, or deal with the version switcher.
   • Cons: Adds a new github action, which needs to clone the entire napari.github.io repo for every deployment, meaning that on every commit we would have a pretty expensive CI run.
2. Use javascript to "trick" the version switcher (I tried experimenting with redirecting the contributing pages to always the latest version but tell the switcher we were still in the old version)
   • Pros: no github action, all is taken care of in the build side.
   • Cons: Very complicated javascript, unless this is coming from the theme (not even sure if possible?) The way the PyData Sphinx theme keeps track of the versions is not very compatible with this solution, but maybe long term there is a case for an upstream implementation. I just don't know.
3. Build unversioned pages in a different folder: essentially, build two sites (one with versioning, the other without) and glue them together
   • Pros: Only needs Sphinx adjustments, and a makefile to build both sites.
   • Cons: All internal links between "sites" become external links (can be fixed with intersphinx), some navigation is broken and needs to be fixed with creative solutions.
4. Add copying logic to napari.github.io: this is essentially 1, but implemented on the napari.github.io side.
   • Pros: Doesn't change current build, requires one script/makefile on napari.github.io
   • Cons: Changes the philosophy of napari.github.io from a purely artifacts-storing repo to have some logic in it.

I hope this is clear, and I'd love some input on the possible solutions. Personally, after experimenting with all of those, I am leaning towards 4 just because it would be very simple to implement and maintain. But I would understand arguments against it.

As a side note, I know of other projects dealing with the same issue but no real solutions for it yet. If you have other ideas please share!