Allow for documentation versioning

[cicdw]

Relevant but not necessary for us to do this ourselves: vuejs/vuepress#857

[cicdw]

I really want to get this out but there are two hurdles I see:

• we need a place to store old version compiled documentation files (is there someplace on our doc-hosting server we could put this @jlowin ?)
• we should decide whether to also version the tutorials

[jlowin]

Would it be crazy to simply add a version directory inside /docs which simply contains a copy of all documentation files from that version? Basically: cp /docs /docs/versions/0.3.2 (without copying the versions recursively, of course)

[cicdw]

Hmmm I think it would only be slightly crazy; that could grow to be a lot of baggage (images, etc.) over time and really clog up the repo. But at this exact moment, especially if we just want this ability sooner rather than later, that is totally reasonable in my book.

[jlowin]

I have zero expertise in this so it's probably safe to ignore me :)

We can always use git to retrieve the historical docs, so any decision is reversible.

[cicdw]

I'm leaning towards only versioning the API docs (avoids having to worry about image versioning, etc. for the tutorials) --> what do y'all think @jlowin @joshmeek ?

[joshmeek]

I would support API doc versioning because it seems like the most frequently changed among the suite. However if features used in tutorials change in breaking ways then those too will need to be updated.

[cicdw]

Right - updating is one thing, but actually keeping all previous versions of tutorials is another

[joshmeek]

Hmm good point. How hard is it to enable full support for documentation versioning?

If we went with full documentation versioning (not just API) we could provide some mechanism where a deprecated version of prefect documents exists outside of the repo. Although that then boils down to backwards compatibility.

[cicdw]

There are two issues with doing full versioning:

• the UI aspect: making a simple dropdown on the API link in the navbar is very easy; if we versinoined the entire doc suite, how would we expose this in the docs UI? I guess a "Version" navbar link?
• all images are stored in .vuepress/public and can be referenced without knowing their location; if we versioned everything, we'd also have to figure out how to handle the images

[cicdw]

Ok so I stand by my claim that it would be "easy" but very messy --> the .vuepress/config.js file controls the display of the sidebar, and we would need to have an explicitly configured sidebar for each API version.....

[cicdw]

@dylanbhughes do you have any ideas about the best way to do API doc-versioning in vuepress?

[cicdw]

I just revisited this and it will also require us to maintain a sidebar in our master .vuepress/config.js for every API version... there's just got to be a better way

[cicdw]

@jlowin suggested a possible route forward here: store all the necessary artifacts / files in an appropriate subdirectory of docs/api/versionNUM in github, and then actually use javascript to dynamically create the correct sidebar for that API version link (.vuepress/config.js should be able to execute javascript, after all).