-
Notifications
You must be signed in to change notification settings - Fork 30
Description
Problem
While working on deploying TryExamples in SciPy's docs, I encountered
WARNING: the jupyterlite_sphinx extension does not declare if it is safe for parallel reading,
assuming it isn't - please ask the extension author to check and make it explicit
WARNING: doing serial read
This warning occurs when one tries to do a parallel documentation build and an extension in-play has not been marked as parallel read safe.
Proposed Solution
We can check if everything is actually parallel read safe. If so: as described here, https://www.sphinx-doc.org/en/master/extdev/index.html#extension-metadata, we could have the setup function in jupyterlite_sphinx.py return a dictionary containing the proper metadata.
It would look like
...
# Copy optional try examples runtime config if it exists.
try_examples_config_path = Path(app.srcdir) / "try_examples.json"
if try_examples_config_path.exists():
copy_asset(str(try_examples_config_path), app.outdir)
return {"parallel_read_safe": True}we wouldn't have to give a value for "parallel_write_safe", because it already defaults to True. If something is not parallel read safe (if so, most likely in the TryExamplesDirective), we should try to make it parallel read safe.
Additional context
Here's the setup function for the doctest extension to show an example of the metadata getting set