Repository: PrefectHQ/prefect

Issue:
Allow for documentation versioning
Relevant but not necessary for us to do this ourselves: https://github.com/vuejs/vuepress/issues/857


Discussion:
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
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)
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.
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.
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 ?
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.
Right - updating is one thing, but actually keeping all previous versions of tutorials is another
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. 
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
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.....
@dylanbhughes do you have any ideas about the best way to do API doc-versioning in vuepress?
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
@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).

Resolving patch:
diff --git a/docs/generate_docs.py b/docs/generate_docs.py
--- a/docs/generate_docs.py
+++ b/docs/generate_docs.py
@@ -263,7 +263,7 @@ def generate_coverage():
     """
 
     # write file for VuePress
-    with open("api/coverage.md", "w+") as f:
+    with open("api/unreleased/coverage.md", "w+") as f:
         f.write(
             textwrap.dedent(
                 """
@@ -357,12 +357,12 @@ def create_tutorial_notebooks(tutorial):
         """
     ).lstrip()
 
-    shutil.rmtree("api", ignore_errors=True)
-    os.makedirs("api", exist_ok=True)
+    shutil.rmtree("api/unreleased", ignore_errors=True)
+    os.makedirs("api/unreleased", exist_ok=True)
     generate_coverage()
 
     ## UPDATE README
-    with open("api/README.md", "w+") as f:
+    with open("api/unreleased/README.md", "w+") as f:
         f.write(
             textwrap.dedent(
                 """
@@ -396,7 +396,7 @@ def create_tutorial_notebooks(tutorial):
             f.write(auto_generated_footer)
 
     ## UPDATE CHANGELOG
-    with open("api/changelog.md", "w+") as f:
+    with open("api/unreleased/changelog.md", "w+") as f:
         f.write(
             textwrap.dedent(
                 """
@@ -419,7 +419,7 @@ def create_tutorial_notebooks(tutorial):
             page.get("classes", []),
             page.get("functions", []),
         )
-        fname = f"api/{fname}"
+        fname = f"api/unreleased/{fname}"
         directory = os.path.dirname(fname)
         if directory:
             os.makedirs(directory, exist_ok=True)


Test patch: