Versioned docs with the ability to toggle

[jlstevens]

In holoviz/geoviews#188 we discuss a feature we have long wanted for docs: versioned docs that you can easily toggle between. This would involve building to a directory containing the version to upload to S3 and some javascript/UI to toggle between the docs versions.

[jsignell]

An alternative to this would be to just allow access to stable and latest docs (this is what dask does). They could be hosted on different sites - for instance panel.pyviz.org and panel.pyviz-dev.org. And there could be dropdown on each site that refers to the other.

This would solve the storage issue because we would only ever be storing 2 versions and they would be in different repos. We are already building dev docs for lots of projects so it'd be straightforward to implement this approach.

These would be the steps (using panel as an example repo):

1. Setup a custom domain at panel.pyviz-dev.org and link it to the repo
2. Make sure that the dev build points to pyviz-dev/panel rather than ioam-docs/panel-dev
3. Have the dev site build on a real release as well as a dev release - so that the dev site is never behind.
4. Make a version dropdown to switch between sites (mimic bokeh)

[jsignell]

@pyviz/pyviz-dev what do people think of the approach outlined above?

[philippjfr]

It seems like a reasonable first step but I really do think we should keep builds for at least all the current micro releases (e.g. if we are on 1.11.3, I'd expect 1.11.0, 1.11.1 and 1.11.2 to also be present) and the last few minor releases (e.g. if we're on 1.11.x I think 1.10.x and 1.9.x should also be there).

[jbednar]

I think we should set it up to be able to keep all numbered releases plus the most recent dev release, and then per website we can have policies about removing old ones. Philipp's suggestion on which ones to keep sounds reasonable to me.

For people to get stable URLs, we presumably need to have the top-level sites redirect userrs into the numbered locations, but to be polite it would be nice if that only happened when selecting an actual docs page. E.g. I'm always a little annoyed when I go to the dask docs and end up at http://docs.dask.org/en/latest; I always have to trim off "en/latest" when I want to pass the URL to someone or link it into my site. It's good if a deeply buried page has the full URL, so that it's permanent when passing it around, but I'd want the top-level pages always to be en/latest without having to say so.