docs,Skylark: fix formatting in Args.html
Also add a sentence explaining that
"memory-efficient command lines" means Bazel
constructs them lazily.
@@ -759,26 +759,28 @@ public class SkylarkActionFactory implements SkylarkValue {
name = "Args",
category = SkylarkModuleCategory.BUILTIN,
doc =
- "module providing methods for building memory-efficient command lines.<br><br>"
- + "See <a href=\"actions.html#run\">ctx.actions.run()</a> or ."
- + "<a href=\"actions.html#run_shell\">ctx.actions.run_shell()</a>"
+ "Module providing methods to build memory-efficient command lines.<br><br>"
+ + "The command lines are memory-efficient because Bazel doesn't fully construct them"
+ + " until just before executing the action. "
+ + "See <a href=\"actions.html#run\">ctx.actions.run()</a> or "
+ + "<a href=\"actions.html#run_shell\">ctx.actions.run_shell()</a>.<br>"
+ "Example:"
+ "<pre class=language-python>\n"
+ "# foo_deps and bar_deps are each a large depset of artifacts\n"
+ "args = ctx.actions.args()\n"
+ "args.add(\"--foo\")\n"
+ "args.add(foo_deps)\n"
- + "args.add(\"--bar\")"
- + "args.add(bar_deps, join_with=\":\")\n"
+ + "args.add(\"--bar\")\n"
+ + "args.add(bar_deps, join_with=\",\")\n"
+ "ctx.run(\n"
+ " arguments = args,\n"
+ " ...\n"
+ ")\n"
+ "# Expands to [\n"
- + "# \"--foo\",\""
- + "# ...artfacts from foo_deps,\n"
+ + "# \"--foo\",\n"
+ + "# ...artifacts from foo_deps,\n"
+ "# \"--bar\",\n"
- + "# ...artifacts from bar_deps joined with ':',\n"
+ + "# ...artifacts from bar_deps joined with ',',\n"
+ "# ]"
+ "</pre>"
)
