enable worker by default so its used when available

Author: rickeylev

docs/BUILD.bazel

@@ -70,7 +70,6 @@ sphinx_docs(
     strip_prefix = package_name() + "/",
     tags = ["docs"],
     target_compatible_with = _TARGET_COMPATIBLE_WITH,
-    use_persistent_workers = True,
     deps = [
         ":bzl_api_docs",
         ":py_api_srcs",

sphinxdocs/docs/index.md

@@ -11,6 +11,29 @@ documentation. It comes with:
 While it is primarily oriented towards docgen for Starlark code, the core of it
 is agnostic as to what is being documented.
 
+### Optimization
+
+Normally, Sphinx keeps various cache files to improve incremental building.
+Unfortunately, programs performing their own caching don't interact well
+with Bazel's model of precisely declaring and strictly enforcing what are
+inputs, what are outputs, and what files are available when running a program.
+The net effect is programs don't have a prior invocation's cache files
+available.
+
+There are two mechanisms available to make some cache available to Sphinx under
+Bazel:
+
+* Disable sandboxing, which allows some files from prior invocations to be
+  visible to subsequent invocations. This can be done multiple ways:
+  * Set `tags = ["no-sandbox"]` on the `sphinx_docs` target
+  * `--modify_execution_info=SphinxBuildDocs=+no-sandbox` (Bazel flag)
+  * `--strategy=SphinxBuildDocs=local`  (Bazel flag)
+* Use persistent workers (enabled by default) by setting
+  `allow_persistent_workers=True` on the `sphinx_docs` target. Note that other
+  Bazel flags can disable using workers even if an action supports it. Setting
+  `--strategy=SphinxBuildDocs=dynamic,worker,local,sandbox` should tell Bazel
+  to use workers if possible, otherwise fallback to non-worker invocations.
+
 
 ```{toctree}
 :hidden:

sphinxdocs/private/sphinx.bzl

@@ -103,7 +103,7 @@ def sphinx_docs(
         strip_prefix = "",
         extra_opts = [],
         tools = [],
-        use_persistent_workers = False,
+        allow_persistent_workers = True,
         **kwargs):
     """Generate docs using Sphinx.
 
@@ -143,8 +143,9 @@ def sphinx_docs(
         tools: {type}`list[label]` Additional tools that are used by Sphinx and its plugins.
             This just makes the tools available during Sphinx execution. To locate
             them, use {obj}`extra_opts` and `$(location)`.
-        use_persistent_workers: {type}`bool` (experimental) If enable, use a persistent
-            worker to run Sphinx for improved incremental, caching, and startup performance.
+        allow_persistent_workers: {type}`bool` (experimental) If true, allow
+            using persistent workers for running Sphinx, if Bazel decides to do so.
+            This can improve incremental building of docs.
         **kwargs: {type}`dict` Common attributes to pass onto rules.
     """
     add_tag(kwargs, "@rules_python//sphinxdocs:sphinx_docs")
@@ -168,7 +169,7 @@ def sphinx_docs(
         source_tree = internal_name + "/_sources",
         extra_opts = extra_opts,
         tools = tools,
-        use_persistent_workers = use_persistent_workers,
+        allow_persistent_workers = allow_persistent_workers,
         **kwargs
     )
 
@@ -213,7 +214,7 @@ def _sphinx_docs_impl(ctx):
             source_path = source_dir_path,
             output_prefix = paths.join(ctx.label.name, "_build"),
             inputs = inputs,
-            use_persistent_workers = ctx.attr.use_persistent_workers,
+            allow_persistent_workers = ctx.attr.allow_persistent_workers,
         )
         outputs[format] = output_dir
         per_format_args[format] = args_env
@@ -253,7 +254,7 @@ _sphinx_docs = rule(
             cfg = "exec",
             doc = "Additional tools that are used by Sphinx and its plugins.",
         ),
-        "use_persistent_workers": attr.bool(
+        "allow_persistent_workers": attr.bool(
             doc = "(experimental) Whether to invoke Sphinx as a persistent worker.",
             default = False,
         ),
@@ -263,7 +264,7 @@ _sphinx_docs = rule(
     },
 )
 
-def _run_sphinx(ctx, format, source_path, inputs, output_prefix, use_persistent_workers):
+def _run_sphinx(ctx, format, source_path, inputs, output_prefix, allow_persistent_workers):
     output_dir = ctx.actions.declare_directory(paths.join(output_prefix, format))
 
     run_args = []  # Copy of the args to forward along to debug runner
@@ -326,7 +327,7 @@ def _run_sphinx(ctx, format, source_path, inputs, output_prefix, use_persistent_
     # requirements and disable workers. Thus, we can't assume that these
     # exec requirements will actually be respected.
     execution_requirements = {}
-    if use_persistent_workers:
+    if allow_persistent_workers:
         execution_requirements["supports-workers"] = "1"
         execution_requirements["requires-worker-protocol"] = "json"