Skip to content

Adding metadata for parallel_read_safe #146

@steppi

Description

@steppi

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

https://github.com/sphinx-doc/sphinx/blob/1281b158b4c674de84135518065739f641c5ce15/sphinx/ext/doctest.py#L566-L583

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions