Better build + instructions for automated openapi docs

[cholmes]

Discussed on our call on April 22:

People have been directly editing the generated OpenAPI docs. We decided that ideally on dev we just have the fragments, and users can build the current state themselves locally. And master will generate them, and upload to stacspec.org (#434).

So this issue is to get the automated build process down to make sure people don't commit the generated openapi docs to dev, and that the process is done right for master (possibly check to make sure they are there, and also that they don't get edited manually).

[m-mohr]

I don't think we can fluently manage that the master has generated files and dev hasn't. This will eventually lead to problems once we need to merge master into dev again (for whatever reason). We can probably manage that they are generated into gh-pages and then made available there per branch. But maybe others have scripts for that, which work that way.

[cholmes]

Yeah, I wasn't sure if there'd be a way to do it, but thought we might come up with something clever. Short of that, I think at the least we could put up a CI test that prevents people from changing the generated docs - like don't accept the PR if it edits the autogenerated files.

[cholmes]

Closing this, as I think Matt got this quite a bit better. We can open issues for other specific improvements.