options) {
* accessed by templates, using reflection.
*/
public enum Category {
+ GLOBAL_FUNCTION(
+ "Global functions",
+ "globals",
+ "This section lists the global functions available in Starlark. The list of available"
+ + " functions differs depending on the file type (whether a BUILD file, or a .bzl file,"
+ + " etc)."),
+
CONFIGURATION_FRAGMENT(
"Configuration Fragments",
+ "fragments",
"Configuration fragments give rules access to "
- + "language-specific parts of "
+ + "language-specific parts of "
+ "configuration. "
+ "Rule implementations can get them using "
- + "ctx."
+ + "ctx."
+ "fragments.[fragment name]"),
PROVIDER(
"Providers",
+ "providers",
"This section lists providers available on built-in rules. See the Rules page for more on"
- + " providers."),
+ + " providers. These symbols are available only in .bzl files."),
- BUILTIN("Built-in Types", "This section lists types of Starlark objects."),
+ BUILTIN(
+ "Built-in Types",
+ "builtins",
+ "This section lists types of Starlark objects. With some exceptions, these type names are"
+ + " not valid Starlark symbols; instances of them may be acquired through different"
+ + " means."),
// Used for top-level modules of functions in the global namespace. Such modules will always
// be usable solely by accessing their members, via modulename.funcname() or
// modulename.constantname.
// Examples: attr, cc_common, config, java_common
- TOP_LEVEL_MODULE(null, null),
+ TOP_LEVEL_MODULE(
+ "Top-level Modules",
+ "toplevel",
+ "This section lists top-level modules. These symbols are available only in .bzl files."),
CORE(
"Core Starlark data types",
+ "core",
"This section lists the data types of the Starlark"
- + " core language.");
+ + " core language. With some exceptions, these type names are not valid Starlark"
+ + " symbols; instances of them may be acquired through different means.");
// Maps (essentially free-form) strings in annotations to permitted categories.
- static Category of(StarlarkBuiltin annot) {
+ public static Category of(StarlarkBuiltin annot) {
switch (annot.category()) {
case DocCategory.CONFIGURATION_FRAGMENT:
return CONFIGURATION_FRAGMENT;
@@ -283,12 +205,14 @@ static Category of(StarlarkBuiltin annot) {
}
}
- private Category(String title, String description) {
+ Category(String title, String path, String description) {
this.title = title;
+ this.path = path;
this.description = description;
}
private final String title;
+ private final String path;
private final String description;
public String getTitle() {
@@ -299,8 +223,8 @@ public String getDescription() {
return description;
}
- public String getTemplateIdentifier() {
- return name().toLowerCase().replace("_", "-");
+ public String getPath() {
+ return path;
}
}
}
diff --git a/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java b/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java
index 38e9becd6f46b5..d7f99dae6ff566 100644
--- a/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java
+++ b/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java
@@ -15,8 +15,9 @@
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
-import com.google.devtools.build.docgen.starlark.StarlarkBuiltinDoc;
+import com.google.devtools.build.docgen.StarlarkDocumentationProcessor.Category;
import com.google.devtools.build.docgen.starlark.StarlarkDocExpander;
+import com.google.devtools.build.docgen.starlark.StarlarkDocPage;
import com.google.devtools.build.lib.analysis.ConfiguredRuleClassProvider;
import com.google.devtools.build.lib.util.Classpath.ClassPathException;
import com.google.devtools.build.skydoc.fakebuildapi.FakeStarlarkNativeModuleApi;
@@ -33,7 +34,7 @@
*/
public class SymbolFamilies {
private final ImmutableList nativeRules;
- private final ImmutableMap types;
+ private final ImmutableMap> allDocPages;
// Mappings between Starlark names and Starlark entities generated from the fakebuildapi.
private final ImmutableMap globals;
@@ -51,7 +52,7 @@ public SymbolFamilies(
expander.ruleExpander, configuredRuleClassProvider, inputDirs, denyList));
this.globals = Starlark.UNIVERSE;
this.bzlGlobals = collectBzlGlobals(configuredRuleClassProvider);
- this.types = StarlarkDocumentationCollector.getAllModules(expander);
+ this.allDocPages = StarlarkDocumentationCollector.getAllDocPages(expander);
}
/*
@@ -78,8 +79,8 @@ public Map getBzlGlobals() {
}
// Returns a mapping between type names and module/type documentation.
- public Map getTypes() {
- return types;
+ public ImmutableMap> getAllDocPages() {
+ return allDocPages;
}
/*
diff --git a/src/main/java/com/google/devtools/build/docgen/annot/GlobalMethods.java b/src/main/java/com/google/devtools/build/docgen/annot/GlobalMethods.java
index c941ad7a6f5833..d6f382f40ae519 100644
--- a/src/main/java/com/google/devtools/build/docgen/annot/GlobalMethods.java
+++ b/src/main/java/com/google/devtools/build/docgen/annot/GlobalMethods.java
@@ -29,22 +29,36 @@
public @interface GlobalMethods {
/** The environment in which the global methods in the annotated class are available. */
enum Environment {
- BUILD("BUILD files"),
- WORKSPACE("WORKSPACE files"),
- MODULE("MODULE.bazel files"),
- BZL(".bzl files"),
- ALL("All Starlark files");
+ BUILD(
+ "BUILD files",
+ "This page contains global methods available in BUILD files. See also the Build"
+ + " Encyclopedia for extra functions and build rules,"
+ + " which can also be used in BUILD files."),
+ WORKSPACE("WORKSPACE files", "This page contains global methods available in WORKSPACE files."),
+ MODULE(
+ "MODULE.bazel files", "This page contains global methods available in MODULE.bazel files."),
+ BZL(".bzl files", "This page contains global methods available in all .bzl files."),
+ ALL(
+ "All Starlark files",
+ "This page contains global methods available in all Starlark files, including BUILD,"
+ + " WORKSPACE, MODULE.bazel, and all .bzl files.");
private final String title;
+ private final String description;
- Environment(String title) {
+ Environment(String title, String description) {
this.title = title;
+ this.description = description;
}
public String getTitle() {
return title;
}
+ public String getDescription() {
+ return description;
+ }
+
public String getPath() {
return Ascii.toLowerCase(name());
}
diff --git a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkBuiltinDoc.java b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkBuiltinDoc.java
index 74a9738c4bf9f4..c83bf9bf2c51c8 100644
--- a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkBuiltinDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkBuiltinDoc.java
@@ -1,4 +1,4 @@
-// Copyright 2014 The Bazel Authors. All rights reserved.
+// Copyright 2023 The Bazel Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
@@ -11,155 +11,46 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
+
package com.google.devtools.build.docgen.starlark;
-import com.google.common.base.Preconditions;
-import com.google.common.collect.HashMultimap;
-import com.google.common.collect.ImmutableCollection;
-import com.google.common.collect.ImmutableList;
-import com.google.common.collect.ImmutableSortedSet;
-import com.google.common.collect.Iterables;
-import com.google.common.collect.Multimap;
-import java.text.Collator;
-import java.util.Collection;
-import java.util.Comparator;
-import java.util.Locale;
-import java.util.TreeMap;
-import javax.annotation.Nullable;
import net.starlark.java.annot.StarlarkBuiltin;
-import net.starlark.java.annot.StarlarkMethod;
-
-/**
- * A class representing documentation for a Starlark built-in object with its {@link StarlarkModule}
- * annotation and with the {@link StarlarkMethod} methods it documents.
- */
-public final class StarlarkBuiltinDoc extends StarlarkDoc {
- private final StarlarkBuiltin module;
- private final String title;
- private final Class classObject;
- private final Multimap javaMethods;
- private TreeMap methodMap;
- @Nullable private StarlarkConstructorMethodDoc javaConstructor;
- private final boolean isTopLevel;
+/** A documentation page for a Starlark builtin type. */
+public final class StarlarkBuiltinDoc extends StarlarkDocPage {
private static final String SOURCE_ROOT = "src/main/java";
- private static final String NO_SOURCE_FILE_VALUE = "NONE";
- public StarlarkBuiltinDoc(
- StarlarkBuiltin module, String title, Class classObject, StarlarkDocExpander expander) {
- this(module, title, classObject, expander, false);
- }
+ private final StarlarkBuiltin starlarkBuiltin;
+ private final Class classObject;
public StarlarkBuiltinDoc(
- StarlarkBuiltin module,
- String title,
- Class classObject,
- StarlarkDocExpander expander,
- boolean isTopLevel) {
+ StarlarkBuiltin starlarkBuiltin, Class classObject, StarlarkDocExpander expander) {
super(expander);
- this.module =
- Preconditions.checkNotNull(
- module, "Class has to be annotated with StarlarkBuiltin: %s", classObject);
- this.title = title;
+ this.starlarkBuiltin = starlarkBuiltin;
this.classObject = classObject;
- this.methodMap = new TreeMap<>(Collator.getInstance(Locale.US));
- this.javaMethods = HashMultimap.create();
- this.isTopLevel = isTopLevel;
}
@Override
public String getName() {
- return module.name();
+ return starlarkBuiltin.name();
}
@Override
public String getRawDocumentation() {
- return module.doc();
+ return starlarkBuiltin.doc();
}
+ @Override
public String getTitle() {
- return title;
- }
-
- public StarlarkBuiltin getAnnotation() {
- return module;
+ return starlarkBuiltin.name();
}
public Class getClassObject() {
return classObject;
}
- public void setConstructor(StarlarkConstructorMethodDoc method) {
- Preconditions.checkState(
- javaConstructor == null,
- "Constructor method doc already set for %s:\n existing: %s\n attempted: %s",
- getName(),
- javaConstructor,
- method);
- javaConstructor = method;
- }
-
- public void addMethod(StarlarkJavaMethodDoc method) {
- if (!method.documented()) {
- return;
- }
-
- String shortName = method.getName();
- Collection overloads = javaMethods.get(shortName);
- if (!overloads.isEmpty()) {
- method.setOverloaded(true);
- // Overload information only needs to be updated if we're discovering the first overload
- // (= the second method of the same name).
- if (overloads.size() == 1) {
- Iterables.getOnlyElement(overloads).setOverloaded(true);
- }
- }
- javaMethods.put(shortName, method);
-
- // If the method is overloaded, getName() now returns a longer,
- // unique name including the names of the parameters.
- StarlarkMethodDoc prev = methodMap.put(method.getName(), method);
- if (prev != null && !prev.getMethod().equals(method.getMethod())) {
- throw new IllegalStateException(
- String.format(
- "Starlark type '%s' (%s) has distinct overloads of %s: %s, %s",
- module.name(), classObject, method.getName(), method.getMethod(), prev.getMethod()));
- }
- }
-
- public boolean javaMethodsNotCollected() {
- return javaMethods.isEmpty();
- }
-
- public Collection getJavaMethods() {
- ImmutableSortedSet.Builder methods =
- new ImmutableSortedSet.Builder<>(Comparator.comparing(StarlarkMethodDoc::getName));
-
- if (javaConstructor != null) {
- methods.add(javaConstructor);
- }
- methods.addAll(javaMethods.values());
- return methods.build();
- }
-
- public ImmutableCollection getMethods() {
- ImmutableList.Builder methods = ImmutableList.builder();
- if (javaConstructor != null) {
- methods.add(javaConstructor);
- }
- return methods.addAll(methodMap.values()).build();
- }
-
- @Nullable
- public StarlarkConstructorMethodDoc getConstructor() {
- return javaConstructor;
- }
-
+ @Override
public String getSourceFile() {
- if (isTopLevel) {
- return NO_SOURCE_FILE_VALUE;
- }
-
String[] parts = classObject.getName().split("\\$", -1);
return String.format("%s/%s.java", SOURCE_ROOT, parts[0].replace('.', '/'));
}
diff --git a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDoc.java b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDoc.java
index 582a0dad9fdab7..86e29f4ebcdef1 100644
--- a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDoc.java
@@ -14,6 +14,7 @@
package com.google.devtools.build.docgen.starlark;
import com.google.common.collect.ImmutableList;
+import com.google.devtools.build.docgen.StarlarkDocumentationProcessor.Category;
import com.google.devtools.build.lib.collect.nestedset.NestedSet;
import java.lang.reflect.Method;
import java.util.Arrays;
@@ -29,9 +30,7 @@
import net.starlark.java.eval.Tuple;
/** Abstract class for containing documentation for a Starlark syntactic entity. */
-abstract class StarlarkDoc {
- protected static final String TOP_LEVEL_ID = "globals";
-
+public abstract class StarlarkDoc {
private final StarlarkDocExpander expander;
protected StarlarkDoc(StarlarkDocExpander expander) {
@@ -63,28 +62,29 @@ protected String getTypeAnchor(Class returnType, Class generic1) {
protected String getTypeAnchor(Class type) {
if (type.equals(Boolean.class) || type.equals(boolean.class)) {
- return "bool";
+ return "bool";
} else if (type.equals(int.class) || type.equals(Integer.class)) {
- return "int";
+ return "int";
} else if (type.equals(String.class)) {
- return "string";
+ return "string";
} else if (Map.class.isAssignableFrom(type)) {
- return "dict";
+ return "dict";
} else if (type.equals(Tuple.class)) {
- return "tuple";
+ return "tuple";
} else if (type.equals(StarlarkList.class) || type.equals(ImmutableList.class)) {
- return "list";
+ return "list";
} else if (type.equals(Sequence.class)) {
- return "sequence";
+ return "sequence";
} else if (type.equals(Void.TYPE) || type.equals(NoneType.class)) {
- return "None";
+ return "None";
} else if (type.equals(NestedSet.class)) {
- return "depset";
+ return "depset";
} else if (StarlarkAnnotations.getStarlarkBuiltin(type) != null) {
- StarlarkBuiltin module = StarlarkAnnotations.getStarlarkBuiltin(type);
- if (module.documented()) {
- return String.format("%1$s",
- module.name());
+ StarlarkBuiltin starlarkBuiltin = StarlarkAnnotations.getStarlarkBuiltin(type);
+ if (starlarkBuiltin.documented()) {
+ return String.format(
+ "%2$s",
+ Category.of(starlarkBuiltin).getPath(), starlarkBuiltin.name());
}
}
return Starlark.classType(type);
diff --git a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDocPage.java b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDocPage.java
new file mode 100644
index 00000000000000..bb4a8757b94c30
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDocPage.java
@@ -0,0 +1,111 @@
+// Copyright 2023 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+package com.google.devtools.build.docgen.starlark;
+
+import com.google.common.base.Preconditions;
+import com.google.common.collect.HashMultimap;
+import com.google.common.collect.ImmutableCollection;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableSortedSet;
+import com.google.common.collect.Iterables;
+import com.google.common.collect.Multimap;
+import java.text.Collator;
+import java.util.Collection;
+import java.util.Comparator;
+import java.util.Locale;
+import java.util.TreeMap;
+import javax.annotation.Nullable;
+
+/**
+ * A typical Starlark documentation page, containing a bunch of field/method documentation entries.
+ */
+public abstract class StarlarkDocPage extends StarlarkDoc {
+ private final Multimap javaMethods;
+ private final TreeMap methodMap;
+ @Nullable private StarlarkConstructorMethodDoc javaConstructor;
+
+ protected StarlarkDocPage(StarlarkDocExpander expander) {
+ super(expander);
+ this.methodMap = new TreeMap<>(Collator.getInstance(Locale.US));
+ this.javaMethods = HashMultimap.create();
+ }
+
+ public abstract String getTitle();
+
+ public void setConstructor(StarlarkConstructorMethodDoc method) {
+ Preconditions.checkState(
+ javaConstructor == null,
+ "Constructor method doc already set for %s:\n existing: %s\n attempted: %s",
+ getName(),
+ javaConstructor,
+ method);
+ javaConstructor = method;
+ }
+
+ public void addMethod(StarlarkJavaMethodDoc method) {
+ if (!method.documented()) {
+ return;
+ }
+
+ String shortName = method.getName();
+ Collection overloads = javaMethods.get(shortName);
+ if (!overloads.isEmpty()) {
+ method.setOverloaded(true);
+ // Overload information only needs to be updated if we're discovering the first overload
+ // (= the second method of the same name).
+ if (overloads.size() == 1) {
+ Iterables.getOnlyElement(overloads).setOverloaded(true);
+ }
+ }
+ javaMethods.put(shortName, method);
+
+ // If the method is overloaded, getName() now returns a longer,
+ // unique name including the names of the parameters.
+ StarlarkMethodDoc prev = methodMap.put(method.getName(), method);
+ if (prev != null && !prev.getMethod().equals(method.getMethod())) {
+ throw new IllegalStateException(
+ String.format(
+ "Starlark type '%s' has distinct overloads of %s: %s, %s",
+ getName(), method.getName(), method.getMethod(), prev.getMethod()));
+ }
+ }
+
+ public Collection getJavaMethods() {
+ ImmutableSortedSet.Builder methods =
+ new ImmutableSortedSet.Builder<>(Comparator.comparing(StarlarkMethodDoc::getName));
+
+ if (javaConstructor != null) {
+ methods.add(javaConstructor);
+ }
+ methods.addAll(javaMethods.values());
+ return methods.build();
+ }
+
+ public ImmutableCollection getMethods() {
+ ImmutableList.Builder methods = ImmutableList.builder();
+ if (javaConstructor != null) {
+ methods.add(javaConstructor);
+ }
+ return methods.addAll(methodMap.values()).build();
+ }
+
+ @Nullable
+ public StarlarkConstructorMethodDoc getConstructor() {
+ return javaConstructor;
+ }
+
+ /** Returns the path to the source file backing this doc page. */
+ // This method may seem unused, but it's actually used in the template file (starlark-library.vm).
+ public abstract String getSourceFile();
+}
diff --git a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkGlobalsDoc.java b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkGlobalsDoc.java
new file mode 100644
index 00000000000000..1166af0d69e4ce
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkGlobalsDoc.java
@@ -0,0 +1,47 @@
+// Copyright 2023 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.devtools.build.docgen.starlark;
+
+import com.google.devtools.build.docgen.annot.GlobalMethods.Environment;
+
+/** A documentation page for a list of Starlark global methods in the same environment. */
+public final class StarlarkGlobalsDoc extends StarlarkDocPage {
+ private final Environment environment;
+
+ public StarlarkGlobalsDoc(Environment environment, StarlarkDocExpander expander) {
+ super(expander);
+ this.environment = environment;
+ }
+
+ @Override
+ public String getName() {
+ return environment.getPath();
+ }
+
+ @Override
+ public String getRawDocumentation() {
+ return environment.getDescription();
+ }
+
+ @Override
+ public String getTitle() {
+ return environment.getTitle();
+ }
+
+ @Override
+ public String getSourceFile() {
+ return "NONE";
+ }
+}
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env.html
index 9eefe24bff2d17..8c448aa28e443c 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env.html
@@ -17,7 +17,7 @@
Starlark-defined test rules. For your own Starlark rules, you can add an "env"
attribute and use it to populate a
- TestEnvironment
+ TestEnvironment
Provider.
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm
index fe0e48de3ab4b5..d05d3c7995f2d1 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm
@@ -43,7 +43,7 @@
exports_files
glob
select
- workspace
+ workspace
Rules
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/starlark-category.vm b/src/main/java/com/google/devtools/build/docgen/templates/starlark-category.vm
index 1ee5f68ff2524a..13a98279230ce6 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/starlark-category.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/starlark-category.vm
@@ -11,9 +11,9 @@
${description}