From 08777388dbc63a69fee504d4d76b73e7c3e02043 Mon Sep 17 00:00:00 2001
From: Googler
Date: Mon, 10 Jul 2023 13:34:54 -0700
Subject: [PATCH] Sort documentable entities (including rule attributes) in
markdown output
starlark_doc_extract, unlike the legacy documentation extractor, produces a
proto with documentable entities in the same order as encountered in the
source. Thus, to be compatible with both the legacy and the new extractor,
the markdown renderer needs to sort rules/providers/functions/aspects, and
the fields in a given rule, before emitting output.
Since we are messing with the sort order, take the opportunity to sort rule
attributes in the same order as in the documentation for native rules in
Bazel docs. (Legacy Stardoc behavior was to sort everything except "name"
in simple alphabetical order. This means some golden tests will need to be
updated.)
PiperOrigin-RevId: 546966417
Change-Id: I69484168b1584aca662fd285652b3fbb3c1fef09
---
.../devtools/build/skydoc/renderer/BUILD | 1 +
.../build/skydoc/renderer/RendererMain.java | 72 +++++++++++++++++--
.../golden.txt | 46 ++++++------
.../skydoc/testdata/misc_apis_test/golden.txt | 20 +++---
.../multi_level_namespace_test/golden.txt | 46 ++++++------
.../golden.txt | 16 ++---
.../skydoc/testdata/namespace_test/golden.txt | 50 ++++++-------
7 files changed, 157 insertions(+), 94 deletions(-)
diff --git a/src/main/java/com/google/devtools/build/skydoc/renderer/BUILD b/src/main/java/com/google/devtools/build/skydoc/renderer/BUILD
index d7eea1c7f6a2ed..ba797883975e21 100644
--- a/src/main/java/com/google/devtools/build/skydoc/renderer/BUILD
+++ b/src/main/java/com/google/devtools/build/skydoc/renderer/BUILD
@@ -36,6 +36,7 @@ java_library(
"//src/main/java/com/google/devtools/build/skydoc/rendering",
"//src/main/java/com/google/devtools/build/skydoc/rendering/proto:stardoc_output_java_proto",
"//src/main/java/com/google/devtools/common/options",
+ "//third_party:guava",
"//third_party/protobuf:protobuf_java",
],
)
diff --git a/src/main/java/com/google/devtools/build/skydoc/renderer/RendererMain.java b/src/main/java/com/google/devtools/build/skydoc/renderer/RendererMain.java
index a943d42fd44dd4..bf99e340a66e5f 100644
--- a/src/main/java/com/google/devtools/build/skydoc/renderer/RendererMain.java
+++ b/src/main/java/com/google/devtools/build/skydoc/renderer/RendererMain.java
@@ -14,10 +14,15 @@
package com.google.devtools.build.skydoc.renderer;
+import static com.google.common.collect.ImmutableList.toImmutableList;
import static java.nio.charset.StandardCharsets.UTF_8;
+import static java.util.Comparator.comparing;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableMap;
import com.google.devtools.build.skydoc.rendering.MarkdownRenderer;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.AspectInfo;
+import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.AttributeInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.ModuleInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.ProviderInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.RuleInfo;
@@ -28,6 +33,7 @@
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.PrintWriter;
+import java.util.Comparator;
import java.util.List;
/**
@@ -93,10 +99,56 @@ public void println() {
}
}
+ // A copy of com.google.devtools.build.docgen.DocgenConsts.ATTRIBUTE_ORDERING - we duplicate the
+ // ordering here because we intend to move this file from the Bazel tree to the Stardoc repo.
+ private static final ImmutableMap ATTRIBUTE_ORDERING =
+ ImmutableMap.builder()
+ .put("name", -99)
+ .put("deps", -98)
+ .put("src", -97)
+ .put("srcs", -96)
+ .put("data", -95)
+ .put("resource", -94)
+ .put("resources", -93)
+ .put("out", -92)
+ .put("outs", -91)
+ .put("hdrs", -90)
+ .buildOrThrow();
+
+ private static final Comparator ATTRIBUTE_NAME_COMPARATOR =
+ (a, b) -> {
+ int aOrdering = ATTRIBUTE_ORDERING.getOrDefault(a, 0);
+ int bOrdering = ATTRIBUTE_ORDERING.getOrDefault(b, 0);
+ if (aOrdering > bOrdering) {
+ return 1;
+ } else if (aOrdering < bOrdering) {
+ return -1;
+ } else {
+ return Comparator.naturalOrder().compare(a, b);
+ }
+ };
+
+ private static RuleInfo withSortedRuleAttributes(RuleInfo ruleInfo) {
+ return ruleInfo.toBuilder()
+ .clearAttribute()
+ .addAllAttribute(
+ ImmutableList.sortedCopyOf(
+ comparing(AttributeInfo::getName, ATTRIBUTE_NAME_COMPARATOR),
+ ruleInfo.getAttributeList()))
+ .build();
+ }
+
private static void printRuleInfos(
PrintWriter printWriter, MarkdownRenderer renderer, List ruleInfos)
throws IOException {
- for (RuleInfo ruleProto : ruleInfos) {
+ // rules are printed sorted by their qualified name, and their attributes are sorted by name,
+ // with ATTRIBUTE_ORDERING specifying a fixed sort order for some standard attributes.
+ ImmutableList sortedRuleInfos =
+ ruleInfos.stream()
+ .map(RendererMain::withSortedRuleAttributes)
+ .sorted(comparing(RuleInfo::getRuleName))
+ .collect(toImmutableList());
+ for (RuleInfo ruleProto : sortedRuleInfos) {
printWriter.println(renderer.render(ruleProto.getRuleName(), ruleProto));
printWriter.println();
}
@@ -105,7 +157,10 @@ private static void printRuleInfos(
private static void printProviderInfos(
PrintWriter printWriter, MarkdownRenderer renderer, List providerInfos)
throws IOException {
- for (ProviderInfo providerProto : providerInfos) {
+ // providers are printed sorted by their qualified name.
+ ImmutableList sortedProviderInfos =
+ ImmutableList.sortedCopyOf(comparing(ProviderInfo::getProviderName), providerInfos);
+ for (ProviderInfo providerProto : sortedProviderInfos) {
printWriter.println(renderer.render(providerProto.getProviderName(), providerProto));
printWriter.println();
}
@@ -114,9 +169,13 @@ private static void printProviderInfos(
private static void printStarlarkFunctions(
PrintWriter printWriter,
MarkdownRenderer renderer,
- List userDefinedFunctions)
+ List starlarkFunctions)
throws IOException {
- for (StarlarkFunctionInfo funcProto : userDefinedFunctions) {
+ // functions are printed sorted by their qualified name.
+ ImmutableList sortedStarlarkFunctions =
+ ImmutableList.sortedCopyOf(
+ comparing(StarlarkFunctionInfo::getFunctionName), starlarkFunctions);
+ for (StarlarkFunctionInfo funcProto : sortedStarlarkFunctions) {
printWriter.println(renderer.render(funcProto));
printWriter.println();
}
@@ -125,7 +184,10 @@ private static void printStarlarkFunctions(
private static void printAspectInfos(
PrintWriter printWriter, MarkdownRenderer renderer, List aspectInfos)
throws IOException {
- for (AspectInfo aspectProto : aspectInfos) {
+ // aspects are printed sorted by their qualified name.
+ ImmutableList sortedAspectInfos =
+ ImmutableList.sortedCopyOf(comparing(AspectInfo::getAspectName), aspectInfos);
+ for (AspectInfo aspectProto : sortedAspectInfos) {
printWriter.println(renderer.render(aspectProto.getAspectName(), aspectProto));
printWriter.println();
}
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/function_wrap_multiple_lines_test/golden.txt b/src/test/java/com/google/devtools/build/skydoc/testdata/function_wrap_multiple_lines_test/golden.txt
index d1e1514f3a36a7..4142acb4c44361 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/function_wrap_multiple_lines_test/golden.txt
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/function_wrap_multiple_lines_test/golden.txt
@@ -5,10 +5,10 @@
## antlr
-antlr(name, Xconversiontimeout, Xdbgconversion, Xdbgst, Xdfa, Xdfaverbose, Xgrtree, Xm,
+antlr(name, deps, srcs, Xconversiontimeout, Xdbgconversion, Xdbgst, Xdfa, Xdfaverbose, Xgrtree, Xm,
Xmaxdfaedges, Xmaxinlinedfastates, Xminswitchalts, Xmultithreaded, Xnfastates, Xnocollapse,
- Xnomergestopstates, Xnoprune, XsaveLexer, Xwatchconversion, debug, depend, deps, dfa, dump,
- imports, language, message_format, nfa, package, profile, report, srcs, trace)
+ Xnomergestopstates, Xnoprune, XsaveLexer, Xwatchconversion, debug, depend, dfa, dump, imports,
+ language, message_format, nfa, package, profile, report, trace)
Runs [ANTLR 3](https://www.antlr3.org//) on a set of grammars.
@@ -30,6 +30,26 @@ Runs [ANTLR 3](https://www.antlr3.org//) on a set of grammars.
+
+ deps |
+
+ List of labels; optional
+
+ The dependencies to use. Defaults to the most recent ANTLR 3 release,
+but if you need to use a different version, you can specify the
+dependencies here.
+
+ |
+
+
+ srcs |
+
+ List of labels; required
+
+ The grammar files to process.
+
+ |
+
Xconversiontimeout |
@@ -201,17 +221,6 @@ Runs [ANTLR 3](https://www.antlr3.org//) on a set of grammars.
|
-
- deps |
-
- List of labels; optional
-
- The dependencies to use. Defaults to the most recent ANTLR 3 release,
-but if you need to use a different version, you can specify the
-dependencies here.
-
- |
-
dfa |
@@ -293,15 +302,6 @@ dependencies here.
|
-
- srcs |
-
- List of labels; required
-
- The grammar files to process.
-
- |
-
trace |
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/golden.txt b/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/golden.txt
index 79768d8225bc3c..b7af0a0cf2c547 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/golden.txt
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/golden.txt
@@ -5,7 +5,7 @@
## my_rule
-my_rule(name, deps, extra_arguments, out, src, tool)
+my_rule(name, deps, src, out, extra_arguments, tool)
This rule exercises some of the build API.
@@ -39,10 +39,13 @@ This rule exercises some of the build API.
|
-
+ src |
- List of strings; optional
+ Label; optional
+
+ The source file.
+
|
@@ -54,13 +57,10 @@ This rule exercises some of the build API.
-
- src |
+
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/multi_level_namespace_test/golden.txt b/src/test/java/com/google/devtools/build/skydoc/testdata/multi_level_namespace_test/golden.txt
index 40aca23c5a6650..51800c50fec8a8 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/multi_level_namespace_test/golden.txt
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/multi_level_namespace_test/golden.txt
@@ -1,11 +1,23 @@
-
+
-## my_namespace.min
+## my_namespace.foo.bar.baz
-my_namespace.min(integers)
+my_namespace.foo.bar.baz()
+
+
+This function does nothing.
+
+
+
+
+
+## my_namespace.math.min
+
+
+my_namespace.math.min(integers)
Returns the minimum of given elements.
@@ -22,7 +34,7 @@ The minimum integer in the given list.
-
+
integers |
required.
@@ -35,12 +47,12 @@ The minimum integer in the given list.
-
+
-## my_namespace.math.min
+## my_namespace.min
-my_namespace.math.min(integers)
+my_namespace.min(integers)
Returns the minimum of given elements.
@@ -57,7 +69,7 @@ The minimum integer in the given list.
|
-
+
integers |
required.
@@ -70,12 +82,12 @@ The minimum integer in the given list.
-
+
-## my_namespace.foo.bar.baz
+## my_namespace.one.three.does_nothing
-my_namespace.foo.bar.baz()
+my_namespace.one.three.does_nothing()
This function does nothing.
@@ -117,15 +129,3 @@ The minimum integer in the given list.
-
-
-## my_namespace.one.three.does_nothing
-
-
-my_namespace.one.three.does_nothing()
-
-
-This function does nothing.
-
-
-
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/multi_level_namespace_test_with_allowlist/golden.txt b/src/test/java/com/google/devtools/build/skydoc/testdata/multi_level_namespace_test_with_allowlist/golden.txt
index 3eaf093d009dc9..27d9df8c2410da 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/multi_level_namespace_test_with_allowlist/golden.txt
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/multi_level_namespace_test_with_allowlist/golden.txt
@@ -1,11 +1,11 @@
-
+
-## my_namespace.min
+## my_namespace.math.min
-my_namespace.min(integers)
+my_namespace.math.min(integers)
Returns the minimum of given elements.
@@ -18,7 +18,7 @@ Returns the minimum of given elements.
|
-
+
integers |
required.
@@ -28,12 +28,12 @@ Returns the minimum of given elements.
-
+
-## my_namespace.math.min
+## my_namespace.min
-my_namespace.math.min(integers)
+my_namespace.min(integers)
Returns the minimum of given elements.
@@ -46,7 +46,7 @@ Returns the minimum of given elements.
|
-
+
integers |
required.
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/namespace_test/golden.txt b/src/test/java/com/google/devtools/build/skydoc/testdata/namespace_test/golden.txt
index cfb8c87ad601b0..7a365dafc26d5c 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/namespace_test/golden.txt
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/namespace_test/golden.txt
@@ -40,19 +40,19 @@ Asserts the two given lists are not empty.
-
+
-## my_namespace.min
+## my_namespace.join_strings
-my_namespace.min(integers)
+my_namespace.join_strings(strings, delimiter)
-Returns the minimum of given elements.
+Joins the given strings with a delimiter.
### Returns
-The minimum integer in the given list.
+The joined string.
### Parameters
@@ -62,12 +62,21 @@ The minimum integer in the given list.
|
-
- integers |
+
+ strings |
required.
- A list of integers. Must not be empty.
+ A list of strings to join.
+
+ |
+
+
+ delimiter |
+
+ optional. default is ", "
+
+ The delimiter to use
|
@@ -75,19 +84,19 @@ The minimum integer in the given list.
-
+
-## my_namespace.join_strings
+## my_namespace.min
-my_namespace.join_strings(strings, delimiter)
+my_namespace.min(integers)
-Joins the given strings with a delimiter.
+Returns the minimum of given elements.
### Returns
-The joined string.
+The minimum integer in the given list.
### Parameters
@@ -97,21 +106,12 @@ The joined string.
-
- strings |
+
+ integers |
required.
- A list of strings to join.
-
- |
-
-
- delimiter |
-
- optional. default is ", "
-
- The delimiter to use
+ A list of integers. Must not be empty.
|