There are three stages of doc generation, each currently done manually.
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
(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.
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
following #314
There are three stages of doc generation, each currently done manually.
autogenerate-bloqs-notebooks.py
takes a list ofBloq
objects and writes stub notebooks and refreshes the docstrings in existing notebooks. The output is unexecuted notebooks that are committed to the repositoryexecute-ntoebooks.py
will execute all of the un-executed source-controlled notebooks and put executed versions indocs/
. 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 indocs/
. These autogenerated files are manually pushed to a separatedocs
git branch.docs/
and turns it to html. This is run via the readthedocs runner.The task is to move to an automated pipeline