Support multiple documentation versions

Adds support for building IDL v1 and v2 docs from the same repo.

Docs from the main branch have been copied to docs/source-1.0.
We've been updating these docs in-place, so the diff is a little
noisy.

Docs for IDL 2 are now in docs/source-2.0. All of the docs that
were previously in docs/source are now here.

Docs that are shared across both versions like ts-ssdk and
implementations.rst are in docs/source-shared. 1.0 and 2.0 docs
refer to these shared docs using symlinks (hope that works ok
in git).

Both 1.0 and 2.0 docs use a shared conf.py file. They load and
compile the shared conf.py from their own dedicated conf.py files
and then override the version number. We can override other settings
here as well. This approach allows us to reuse the configuration and
theme for both 1.0 and 2.0 docs with no added effort. This was
chosen over a branch based strategy to avoid needing to duplicate
configs or remember to update multiple branches.

All docs will now be rooted under a version. So instead of
/index.html, it's /1.0/index.html and /2.0/index.html. root-redirects/
contains HTML files that redirect /index.html to the latest version,
/2.0/index.html (it does this for other top-level html files).

The Makefile was simplified and updated to add html1 and html2
targets. The html target will build both, copy redirects, and
merge the outputs into a single directory under build/html. This is
the same directory we already use to package up docs.

Because a version number is now at the top-level, docs that were
previously under /1.0/ through the actually filename have now been
moved up a level. So /1.0/guides is now at /guides/. Redirects were
added for every file in this directory. This is nice because the 1.0
and 2.0 directory structures are the same _and_ the existing 1.0
links already used for things like /1.0/spec/index.html end up as
the same link (we removed 1.0 from the rst filename, but add it back
because we're now rooting docs under a version).

There are still two TODOs for this update:
1. Adding a banner that 1.0 docs are deprecated.
2. Adding a way to jump between documentation versions.

A few minor 1.0 vs 2.0 IDL tweaks were made in this update but I'm
saving more of that for subsequent commits.

docs/Makefile

@@ -2,35 +2,26 @@
 SPHINXOPTS    =
 SPHINXBUILD   = python3 -msphinx
 SPHINXPROJ    = Smithy
-SOURCEDIR     = source
-BUILDDIR      = build
-
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-	@echo "  openhtml    to preview the built index.html"
 
 install:
 	pip3 install -r requirements.txt .
 	pip3 install -e .
 
 clean:
-	-rm -rf $(BUILDDIR)/*
-
-install-server:
-	pip3 install -r requirements-server.txt
+	-rm -rf build/*
 
-serve: clean
-	sphinx-autobuild source build/html
+html1:
+	@$(SPHINXBUILD) -M html "source-1.0" "build/1.0" $(SPHINXOPTS) $(O)
 
-html:
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+html2:
+	@$(SPHINXBUILD) -M html "source-2.0" "build/2.0" $(SPHINXOPTS) $(O)
 
-openhtml:
-	open "$(BUILDDIR)/html/index.html"
+html: html1 html2 merge-versions
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+merge-versions:
+	mkdir -p build/html
+	cp -R "build/1.0/html" "build/html/1.0"
+	cp -R "build/2.0/html" "build/html/2.0"
+	cp -R "root-redirects/" "build/html"
 
-.PHONY: help Makefile clean openhtml
+.PHONY: Makefile clean

docs/source/conf.py → docs/conf.py

@@ -25,8 +25,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx_tabs.tabs',
-              'smithy']
+extensions = ['sphinx_tabs.tabs', 'smithy']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -42,22 +41,9 @@
 
 # General information about the project.
 project = u'Smithy'
-copyright = u'2019, Amazon Web Services'
+copyright = u'2022, Amazon Web Services'
 author = u'Amazon Web Services'
 
-# This is the version of the Smithy IDL itself. This version uses semver
-# and should be updated each time a new feature or breaking change is made.
-#
-# These versions as replacement for |version| and |release| in rst files,
-# and are used in various other places throughout the built documents.
-#
-# ************************ IMPORTANT **********************************
-# When changing this value, be sure to change the directory inside of
-# source/ to match, and references to the directory in source/index.rst.
-# *********************************************************************
-release = u'1.0'   # The full version of the spec (e.g., "1.0")
-version = release
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -108,63 +94,6 @@
     '**': ['globaltoc.html']
 }
 
-
-# -- Options for HTMLHelp output ------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'Smithy'
-
-
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, 'Smithy.tex', u'Smithy Documentation',
-     u'Amazon Web Services', 'manual'),
-]
-
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'smithy', u'Smithy Documentation',
-     [author], 1)
-]
-
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (master_doc, 'Smithy', u'Smithy Documentation',
-     author, 'Smithy', 'One line description of project.',
-     'Miscellaneous'),
-]
-
 html_favicon = "../themes/smithy/static/favicon.png"
 
 

docs/root-redirects/implementations.html

@@ -0,0 +1,3 @@
+<html>
+  <head><meta http-equiv="refresh" content="0; url=2.0/implementations.html"/></head>
+</html>

docs/root-redirects/index.html

@@ -0,0 +1,3 @@
+<html>
+  <head><meta http-equiv="refresh" content="0; url=2.0/index.html"/></head>
+</html>

docs/root-redirects/quickstart.html

@@ -0,0 +1,3 @@
+<html>
+  <head><meta http-equiv="refresh" content="0; url=2.0/quickstart.html"/></head>
+</html>

docs/source-1.0/conf.py

@@ -0,0 +1,6 @@
+shared_config = "../conf.py"
+exec(compile(source=open(shared_config).read(), filename=shared_config, mode='exec'))
+
+# Place any version specific overrides here.
+release = u'1.0'
+version = release