Stuck on a mysterious error during CI?

Sometimes, tests pass locally but not during CI in GitHub Actions. Those errors can be hard to track down because they are linked to building the documentation or checks of example codes.

Here's a short list of such known errors that can happen, to avoid being stuck on those again once we've lost track months (years?) later:

1. The typical: Package versions tend to change during CI's setup, updating to newest versions. Quite often those contain new warning about future deprecations or syntax changes. Those can be impossible to correct in our own package if they depend on another package (e.g. numpy warning in a scikit package), and can result in failure during tests. Solution: list those in the exclusion list of specific tests or, in case of the documentation test, in a dedicated list found in tests/test_docs.py:

ignored_warnings = ["Starting a Matplotlib GUI outside of the main thread",
                        ".*fetching the attribute.*Polygon.*",]

2. The sneaky: Defining a function with def in an example code (in /docs/source/code, which is used to check that the code snapshots shown in our documentation do work or to create documentation-specific figures) will result in a failure of the CI in GitHub Actions. This failure happens for the exec() in the function test_example_code in tests/test_docs.py. This issue is related to defining global variables through exec(), details here. Solution: use a lambda function, or define the function directly in xdem!

exec(infile.read().replace("plt.show()", "plt.close()"))

3. The mysterious: Building sphinx during CI in GitHub Actions with several cores might result in failure. The cause is as-yet unknown (tried reverting to older sphinx versions without any success). Solution: use a single core.

sphinx.cmd.build.main(["-j", str(N_cores), os.path.join(self.docs_dir, "source/"), os.path.join(self.docs_dir, "build/html")])