docs: add 1.10 legacy docs to switcher.json

[agoose77]

I've pushed a new build of the v1.10 docs to http://awkward-array.org/doc, using our new pydata-sphinx-theme template. It's not perfect, but it also doesn't need to be — it's just for existing v1 users. This path is set to be hidden from indexing, spidering, and analytics.

I've already pushed this to the website, but this change ensures that v1 can be selected from the version dropdown upon future releases, which will wipe the deployed contents of switcher.json

[jpivarski]

The docs-preview doesn't have a switcher as far as I can see, but it's already showing up in the main docs:

The problem with this approach is that the switcher promises to show you the equivalent of whatever page you're on in another version, and the v1 docs have a different structure, so there usually isn't a corresponding page.

Suppose they're on the modern page for ak.from_buffers:

https://awkward-array.org/doc/main/reference/generated/ak.from_buffers.html

and they want to see how the new buffer_key argument corresponds to the old key_format argument, so they want to see the old page for ak.from_buffers:

https://awkward-array.org/doc/1.10/_auto/ak.from_buffers.html

Using the switcher (from the modern page) would take you here:

https://awkward-array.org/doc/1.10/reference/generated/ak.from_buffers.html

which is a 404.

One way to do it, which minimizes effort, is to promise less. If the link to the 1.10 documentation is not a switcher that promises to transform any modern page into an old page, but instead a single link to the most important page in the old docs:

https://awkward-array.org/doc/1.10/api-reference.html

That would do it. It could be a little hyperlink-colored text just below the four panels on the front page.

---

Unrelated to that, can we have the numbered versions be in descending order? The top to switcher items are the latest documentation; it would be more natural if the numbered/older versions don't switch sort direction. We would have noticed that when 2.1.0 is released. Which reminds me, that has to happen this week.

[agoose77]

One way to do it, which minimizes effort, is to promise less. If the link to the 1.10 documentation is not a switcher that promises to transform any modern page into an old page, but instead a single link to the most important page in the old docs:

Yes, I don't think we need to preserve v1 visibility. I'll add a banner, or some such thing.

Unrelated to that, can we have the numbered versions be in descending order? The top to switcher items are the latest documentation; it would be more natural if the numbered/older versions don't switch sort direction. We would have noticed that when 2.1.0 is released. Which reminds me, that has to happen this week.

Good suggestion, I'll make that change here.

[jpivarski]

I should add that we definitely would have gotten complaints that our documentation is broken if someone tries to select 1.10 and gets a 404 page. The idea that the page they want exists under a different URL, which can be found by navigating from the main-1.10 page, would not be most people's first thought.

But if there's a small banner on the homepage that requires them to navigate to what they want, that would do it. (It shouldn't be inline with the badges, which have no more horizontal space and address very different topics from "this documentation, but older." I think the best place is under the four big panels. If users don't find it right away, we can point them to it.)

[agoose77]

I'm not sure whether the theme supports using a version selector with versions that aren't included in the switcher.json. If that happens, i.e. the switcher breaks on 1.10.X, then we can just remove the switcher, and add a banner. In fact, that's what I'll do.

[agoose77]

Thoughts?

[agoose77]

Note that for the next minor release, we need to manually edit switcher.json for now; we don't yet have a fully automated versioning workflow.

[jpivarski]

I like this solution, graphically as well as logically. But could it instead go to this link?

https://awkward-array.org/doc/1.10/api-reference.html

That's the only useful link on the existing page, and the way it's formatted, it's not clear that this is the one to go for. Having the banner go to the above will help a lot.

[jpivarski]

Perfect! And now they can do v1 documentation in dark mode. :)