Currently, we have set nbsphinx_execute = "auto" in the Sphinx configuration so that notebooks are not re-executed anytime someone runs tox -e docs, in large part to speed up the build cycle for quick development.
However, even without changing this for local builds, we have the option of changing this on CI, which is where our deployed documentation is built.
Here's what would be different:
The notebooks in the docs will always be the result of a fresh run, so we will no longer to be forced to manually re-execute notebooks e.g., anytime the Qiskit default visualizaions change (#524) or when deprecation warnings are added to our own codebase (possible part of #533), etc.
We will have less control about what output is appearing in the hosted notebooks. Maybe something weird will happen because of a weird random seed. (For the docs to build and deploy successfully, the code must execute without errors, but there could still be something weird in the notebook short of an actual failure.) Conversely, if running a notebook does result in something weird, I'd almost prefer that that is visible to at least us as we glance through the documentation, rather than be something that is not discovered until a user actually tries to use the notebook.
I'm not really sure which I'd prefer, but think it is worth considering merging this. Open to discussion.
Currently, we have set
nbsphinx_execute = "auto"
in the Sphinx configuration so that notebooks are not re-executed anytime someone runstox -e docs
, in large part to speed up the build cycle for quick development.However, even without changing this for local builds, we have the option of changing this on CI, which is where our deployed documentation is built.
Here's what would be different:
I'm not really sure which I'd prefer, but think it is worth considering merging this. Open to discussion.