From 750909cb3c2bd7b47ae02cb78cf4f19c954fc121 Mon Sep 17 00:00:00 2001 From: Ulf Adams Date: Fri, 28 Aug 2015 12:26:59 +0000 Subject: Push local and shard_count documentation. -- MOS_MIGRATED_REVID=101768878 --- .../build/docgen/PredefinedAttributes.java | 47 ++++++++++++++++++---- .../docgen/templates/attributes/test/local.html | 7 ++++ .../templates/attributes/test/shard_count.html | 14 +++++++ .../docgen/templates/attributes/test/size.html | 2 +- .../com/google/devtools/build/lib/Constants.java | 35 ---------------- 5 files changed, 61 insertions(+), 44 deletions(-) create mode 100644 src/main/java/com/google/devtools/build/docgen/templates/attributes/test/local.html create mode 100644 src/main/java/com/google/devtools/build/docgen/templates/attributes/test/shard_count.html (limited to 'src/main/java/com') diff --git a/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java b/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java index bc81f6772a..7e83288765 100644 --- a/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java +++ b/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java @@ -18,7 +18,6 @@ import com.google.common.collect.ImmutableMap; import com.google.common.collect.ImmutableMap.Builder; import com.google.common.io.ByteStreams; import com.google.common.io.Files; -import com.google.devtools.build.lib.Constants; import java.io.IOException; import java.io.InputStream; @@ -27,13 +26,45 @@ import java.util.Map; /** * A class to contain the base definition of common BUILD rule attributes. - * - *

See {@link Constants#COMMON_ATTRIBUTES_DOCFILES}, {@link Constants#BINARY_ATTRIBUTES_DOCFILES} - * and {@link Constants#TEST_ATTRIBUTES_DOCFILES} for the list of files containing the attributes - * description. */ public class PredefinedAttributes { + /** + * List of documentation for common attributes of *_test rules, relative to + * {@link com.google.devtools.build.docgen}. + */ + public static final ImmutableList TEST_ATTRIBUTES_DOCFILES = ImmutableList.of( + "templates/attributes/test/args.html", + "templates/attributes/test/size.html", + "templates/attributes/test/timeout.html", + "templates/attributes/test/flaky.html", + "templates/attributes/test/shard_count.html", + "templates/attributes/test/local.html"); + + /** + * List of common attributes documentation, relative to {@link com.google.devtools.build.docgen}. + */ + public static final ImmutableList COMMON_ATTRIBUTES_DOCFILES = + ImmutableList.of( + "templates/attributes/common/data.html", + "templates/attributes/common/deprecation.html", + "templates/attributes/common/deps.html", + "templates/attributes/common/distribs.html", + "templates/attributes/common/features.html", + "templates/attributes/common/licenses.html", + "templates/attributes/common/tags.html", + "templates/attributes/common/testonly.html", + "templates/attributes/common/visibility.html"); + + /** + * List of documentation for common attributes of *_binary rules, relative to + * {@link com.google.devtools.build.docgen}. + */ + public static final ImmutableList BINARY_ATTRIBUTES_DOCFILES = + ImmutableList.of( + "templates/attributes/binary/args.html", + "templates/attributes/binary/output_licenses.html"); + private static ImmutableMap generateAttributeMap( String commonType, ImmutableList filenames) { Builder builder = @@ -55,11 +86,11 @@ public class PredefinedAttributes { } public static final Map COMMON_ATTRIBUTES = - generateAttributeMap(DocgenConsts.COMMON_ATTRIBUTES, Constants.COMMON_ATTRIBUTES_DOCFILES); + generateAttributeMap(DocgenConsts.COMMON_ATTRIBUTES, COMMON_ATTRIBUTES_DOCFILES); public static final Map BINARY_ATTRIBUTES = - generateAttributeMap(DocgenConsts.BINARY_ATTRIBUTES, Constants.BINARY_ATTRIBUTES_DOCFILES); + generateAttributeMap(DocgenConsts.BINARY_ATTRIBUTES, BINARY_ATTRIBUTES_DOCFILES); public static final Map TEST_ATTRIBUTES = - generateAttributeMap(DocgenConsts.TEST_ATTRIBUTES, Constants.TEST_ATTRIBUTES_DOCFILES); + generateAttributeMap(DocgenConsts.TEST_ATTRIBUTES, TEST_ATTRIBUTES_DOCFILES); } diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/local.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/local.html new file mode 100644 index 0000000000..5bcad595f1 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/local.html @@ -0,0 +1,7 @@ +

Boolean; optional

+ +

Forces the test to be run locally, without sandboxing.

+ +

By default this attribute is set to 0 and the default testing strategy is +used. This is equivalent to providing "local" as a tag +(tags=["local"]).

diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/shard_count.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/shard_count.html new file mode 100644 index 0000000000..f2e76e85f4 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/shard_count.html @@ -0,0 +1,14 @@ +

Non-negative integer less than or equal to 50; +optional

+ +

Specifies the number of parallel shards +to use to run the test.

+ +

This value will override any heuristics used to determine the number of +parallel shards with which to run the test. Note that for some test +rules, this parameter may be required to enable sharding +in the first place. Also see --test_sharding_strategy.

+ +

Sharding requires the test runner to support the test sharding protocol. +If it does not, then it will most likely run every test in every shard, which +is not what you want.

diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/size.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/size.html index 1dea0ae889..9da6c57d80 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/size.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/size.html @@ -1,5 +1,5 @@

String "enormous", "large" "medium" or "small", -default is "medium"

+default is "medium"; optional

How "heavy" the test is.

diff --git a/src/main/java/com/google/devtools/build/lib/Constants.java b/src/main/java/com/google/devtools/build/lib/Constants.java index bfd8054a25..d11a075c26 100644 --- a/src/main/java/com/google/devtools/build/lib/Constants.java +++ b/src/main/java/com/google/devtools/build/lib/Constants.java @@ -39,41 +39,6 @@ public class Constants { public static final String PRELUDE_FILE_DEPOT_RELATIVE_PATH = "tools/build_rules/prelude_bazel"; - /** - * List of common attributes documentation, relative to {@link com.google.devtools.build.docgen}. - */ - public static final ImmutableList COMMON_ATTRIBUTES_DOCFILES = - ImmutableList.of( - "templates/attributes/common/data.html", - "templates/attributes/common/deprecation.html", - "templates/attributes/common/deps.html", - "templates/attributes/common/distribs.html", - "templates/attributes/common/features.html", - "templates/attributes/common/licenses.html", - "templates/attributes/common/tags.html", - "templates/attributes/common/testonly.html", - "templates/attributes/common/visibility.html"); - - /** - * List of documentation for common attributes of *_binary rules, relative to - * {@link com.google.devtools.build.docgen}. - */ - public static final ImmutableList BINARY_ATTRIBUTES_DOCFILES = - ImmutableList.of( - "templates/attributes/binary/args.html", - "templates/attributes/binary/output_licenses.html"); - - /** - * List of documentation for common attributes of *_test rules, relative to - * {@link com.google.devtools.build.docgen}. - */ - public static final ImmutableList TEST_ATTRIBUTES_DOCFILES = - ImmutableList.of( - "templates/attributes/test/args.html", - "templates/attributes/test/size.html", - "templates/attributes/test/timeout.html", - "templates/attributes/test/flaky.html"); - /** * List of file extensions of which baseline coverage generation is supported. */ -- cgit v1.2.3