Automate doc generation and pushing

[mpharrigan]

following #314

There are three stages of doc generation, each currently done manually.

1. autogenerate-bloqs-notebooks.py takes a list of Bloq objects and writes stub notebooks and refreshes the docstrings in existing notebooks. The output is unexecuted notebooks that are committed to the repository
2. (a) execute-ntoebooks.py will execute all of the un-executed source-controlled notebooks and put executed versions in docs/. This is used by the CI to check that the notebooks run successfully. (b) build-reference-docs.py will extract docstrings and stuff and put markdown files in docs/. These autogenerated files are manually pushed to a separate docs git branch.
3. Sphinx takes the executed notebooks, the reference markdown files, and some additional hand-written files in docs/ and turns it to html. This is run via the readthedocs runner.

The task is to move to an automated pipeline

• [ ] I think stage 1 will be manual for now, since the autogenerated output is just a stub for a complete doc and we want developers to write additional hand-authored documentation. We could add a CI check that the autogenerated parts are up-to-date and if they are not the PR author would re-run this script and commit the result
• [ ] Stage 2 should likely be automated but it's not clear exactly how. For runners, we could use github CI or readthedocs. For cadence: we could do every PR, regularly scheduled (nightly?), or try to do it on PRs that would change the output. A concern is that the autogeneration output is not byte-for-byte reproducible. Output contains timestamps and stochastic ordering of outputs. This could create churn or break html cacheing or throw off the "is anything changed" checker.
• [ ] Stage 2 outputs render nicely on GitHub. Should we commit them? With what cadence? How do we handle churn? How would this be automated? A requirement is that this would not disrupt or clutter normal PR review
• [ ] Stage 3 is currently nice and fast and straightforward on readthedocs (c.f. #280 ). We should turn sphinx warnings into errors and maybe have this as a PR CI check
• [ ] Checks for clean notebooks like #190

[mpharrigan]

I documented these stages in a readme file as part of #467

[wjhuggins]

I'll just add here that I'd love it if the executed notebooks were committed to GitHub if possible. It's nice to be able to see them alongside the source.