Catch documentation and examples errors #736
Conversation
rafmudaf
added
bug
This ensures there’s no reliance on the repo struture to find source files
rafmudaf
changed the title
|
This seems like a good change to make to be made aware of any broken notebooks, support! |
rafmudaf
requested review from
RHammond2
and removed request for
bayc and
misi9170
docs/_config.yml
Outdated
| nb_execution_show_tb: True # Shows the stack trace in stdout; its suppressed otherwise | ||
| nb_execution_raise_on_error: true # Stops the Sphinx build if there is an error in a notebook. See https://github.com/executablebooks/jupyter-book/issues/2011 |
There was a problem hiding this comment.
These configurations should be outside the config, but still under sphinx, and have lowercase true as the value. However, this doesn't break the build process.
There was a problem hiding this comment.
Per our conversation a few moments ago, it seems that this is heavily dependent on the version of jupyter-book for where these settings should live. However, neither version solved the issue where it doesn't break the build process.
Jupyter Book v0.14 supports setting this: nb_execution_show_tb: true nb_execution_raise_on_error: true And sphinx-book-theme 0.4.0rc1 is the required version for JupyterBook v0.14. Note that there is an incompatibility with FLORIS docs and JupyterBook v0.15, sphinx-book-theme v1.0.
Mostly just to make the docs build on GitHub to test that it exits on error
|
@RHammond2 I've pinned the Jupyter Book version to v0.14.0 since that one supports the This change now catches any errors in notebook execution during the documentation build process. You can see the failing Actions job on my fork. |
Improve CI configuration to abort when documentation build errors and test for repo dependency in Examples
This pull request adds a setting to the documentation configuration that will stop the build when a notebook within the docs has an error in any code cell. Currently, the documentation is configured to proceed with building the docs even if a notebook errors. This was made clear recently during a FLORIS workshop where errors in the documentation were a surprise because GitHub Actions had not failed.
Another change included here runs the examples in a directory outside of the top-level repository directory. This tests for whether any feature described in the examples is relying on the directory structure of the repository. For example, see #737.
Note accepting this pull request means the documentation CI pipeline will fail. This is expected and must be resolved through other fixes to the documentation ASAP. See #733 for more info.
Additionally, I fixed spelling errors in docstrings throughout the software, and addressed a few warnings from Jupyter Book and Sphinx. Other warnings from autodoc and auto summary Sphinx extensions are suppressed since they are a consequence of autogenerating the API documentation.
Related issue
#733
#737
Impacted areas of the software
Docs
Automated check for running the examples