Add docs site for archives.getmyvax.org

[Mr0grog]

We’ve needed to have some docs around https://archives.getmyvax.org for a while and never gotten around to it. Now that the API and its accompanying docs are disappearing, I wanted to add some docs that live directly on archives.getmyvax.org (so whatever else happens to other sites, the docs stay alongside the archive data).

The docs page got quite long once I’d pasted in all the schemas and sources and ID systems and so on, so I split it up into a few pages and used MkDocs to generate a site from the markdown files.

All the source for the docs site is in the archives directory. There’s a workflow to build the site and upload it to the /docs folder in the univaf-data-snapshots S3 bucket where we serve the archives site from.

This got a bit in the weeds on a few counts:

• Tooling: I poked around at a few docs generators that I had and hadn’t used before. Ultimately I felt like MkDocs (and the Material theme for it) gets us something pretty nice without a giant mess of configuration and without too much extra files and stuff (no React, etc. etc. etc. [TIL Docusaurus 2 is React-based!]). It’s Python, though, which makes the set up weird vs. the rest of the stuff in this repo.

  I also played around with 11ty for a very minimal, JS-based site, but quickly found myself in the weeds on layout concerns, anchors for headings, and so on. You don’t really get much out of the box with it. We can build something more minimal, but I’m not sure that’s really important.

• S3 Website Serving: I decided not to turn it on, which means URLs are not as nice, and there’s a weird index redirect thing I’m doing.

  I’ve never set up S3 in website mode before, and my lesson from today is that it’s not that complicated, but then if you want to force people to go through CloudFront (which we do) and still secure the bucket it’s a little complicated, and then because we are using a Cloudposse Terraform module to manage CloudFront, but not to create and manage the bucket itself, it’s really complicated. Did not feel worth the time to figure out how to do it right, or to unwind our usage of Cloudposse.

  The downside is that this means browsing to /docs/ does not get you /docs/index.html (this still works for the root index.html file, just not for subdirectories). So I had to flip MkDocs's settings to generate <page>.html instead of <page>/index.html.

  Since Mkdocs generates a bunch of files, I also wanted to isolate it all into one directory in S3 (/docs). There’s a kind of dumb index.html I’ve manually written that just uses a <meta> element to redirect browsers to /docs. I think I might be able to do this better by setting default_root_object in the Cloudposse module in Terraform, but I’ll experiment with that later.

Part of https://github.com/usdigitalresponse/univaf/issues/1550.

Screenshot:

[Mr0grog]

TODO: add info about final Postgres and SQLite dumps