Skip to content

Commit

Permalink
Merge branch 'master' into 95-loads
Browse files Browse the repository at this point in the history
Conflicts:
	src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownUtil.java
  • Loading branch information
tetromino committed May 20, 2024
2 parents aed67db + be1a9a8 commit 67640b4
Show file tree
Hide file tree
Showing 22 changed files with 99 additions and 151 deletions.
5 changes: 2 additions & 3 deletions BUILD
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,8 @@ filegroup(
"MODULE.bazel",
"maven_install.json",
"rules_jvm_external.patch",
"//src/main/java/com/google/devtools/build/skydoc/renderer:srcs",
"//src/main/java/com/google/devtools/build/skydoc/rendering:srcs",
"//src/test/java/com/google/devtools/build/skydoc/rendering:srcs",
"//src/main/java/com/google/devtools/build/stardoc/renderer:srcs",
"//src/main/java/com/google/devtools/build/stardoc/rendering:srcs",
"//stardoc:distro_srcs",
"//stardoc/private:distro_srcs",
"//stardoc/proto:distro_srcs",
Expand Down
1 change: 0 additions & 1 deletion MODULE.bazel
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@ bazel_dep(name = "bazel_skylib", version = "1.4.2")
bazel_dep(name = "rules_java", version = "6.3.0")
bazel_dep(name = "rules_jvm_external", version = "5.2")
bazel_dep(name = "rules_license", version = "0.0.7")
bazel_dep(name = "protobuf", version = "21.7", repo_name = "com_google_protobuf")

# Maven artifacts required by Stardoc; keep consistent with deps.bzl
STARDOC_MAVEN_ARTIFACTS = [
Expand Down
7 changes: 7 additions & 0 deletions distro/BUILD
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,12 @@ alias(
actual = "stardoc-%s" % version,
)

strip_internal_only(
name = "distro_module_bazel",
src = "//:MODULE.bazel",
out = "MODULE.bazel",
)

strip_internal_only(
name = "distro_workspace",
src = "//:WORKSPACE",
Expand All @@ -27,6 +33,7 @@ strip_internal_only(
pkg_tar(
name = "distro_srcs",
srcs = [
"distro_module_bazel",
"distro_workspace",
"distro_workspace_bzlmod",
"//:distro_srcs",
Expand Down
14 changes: 14 additions & 0 deletions distro/distro.bzl
Original file line number Diff line number Diff line change
@@ -1,3 +1,17 @@
# Copyright 2024 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.

"""Macros related to distro tarball packaging"""

def strip_internal_only(name, src, out):
Expand Down
14 changes: 5 additions & 9 deletions docs/advanced_stardoc_usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,10 +76,11 @@ Stardoc's output templates are defined using
with utilities and model objects available in the evaluation context.

The full comprehensive list of available utilities top-level objects is available in
[the source for MarkdownRenderer](https://github.com/bazelbuild/bazel/blob/3fcfbe14ddec34889c5e3fe33415af2cf9124e7c/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownRenderer.java#L100).
[the source for MarkdownRenderer](../src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownRenderer.java).

Information available for raw model objects (such rule information) is defined by
Stardoc's underlying [proto schema](https://github.com/bazelbuild/bazel/blob/5eeccd8a647df10d154d3b86e9732e7f263c96db/src/main/java/com/google/devtools/build/skydoc/rendering/proto/stardoc_output.proto).
Stardoc's underlying [proto schema](../stardoc/proto/stardoc_output.proto), vendored
[from the Bazel source tree](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/stardoc_output.proto).

This is a particularly advanced feature of Stardoc, so we would recommend using
one of the existing canonical [templates](../stardoc/templates/markdown_tables) as a
Expand All @@ -97,13 +98,8 @@ fully evaluating a Starlark file. If your changes could be incorporated into
Stardoc, please first consider [contributing](contributing.md) instead.

The proto schema may be found under
[stardoc/proto/stardoc_output.proto](../stardoc/proto/stardoc_output.proto).
Only the `.proto` file itself is provided (this prevents a transitive dependency on
proto rules to support only a very-advanced usecase). We recommend using rules
defined under
[bazelbuild/rules_proto](https://github.com/bazelbuild/rules_proto), creating
your own proto target using this source file, and adding it as a dependency of
your renderer binary.
[stardoc/proto/stardoc_output.proto](../stardoc/proto/stardoc_output.proto), vendored
[from the Bazel source tree](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/stardoc_output.proto).

To configure stardoc to output raw proto instead of markdown, use the `format`
attribute of the [stardoc rule](stardoc_rule.md#stardoc-format). Specify `"proto"`.
Expand Down
20 changes: 10 additions & 10 deletions docs/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,16 +15,16 @@ starting a [GitHub Discussion](https://github.com/bazelbuild/bazel/discussions).

## Stardoc code structure

* The [bazelbuild/stardoc](https://github.com/bazelbuild/stardoc) repository
contains Stardoc's Starlark code alongside Stardoc's prebuilt java binaries (jars).
* The source code for Stardoc's jars can be found under the bazelbuild/bazel source tree
[here](https://github.com/bazelbuild/bazel/tree/master/src/main/java/com/google/devtools/build/skydoc).
Changes to Stardoc's java binaries will thus require creation of pull requests to the
[bazelbuild/bazel](https://github.com/bazelbuild/bazel) repository.
* Changes to Stardoc's source are pulled in by updating bazelbuild/stardoc's dependency
on the bazel source tree and and then rebuilding the binary using bazel. This process
is done periodically by Stardoc's [core contributors](#core-contributors) (generally
with large changes to Stardoc source, and right before cutting a new Stardoc release).
* Stardoc internally relies on Bazel's `starlark_doc_extract` rule to extract
documentation in [proto format](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/stardoc_output.proto)
(vendored into Stardoc's repo in [stardoc/proto/stardoc_output.proto](../src/proto/stardoc_output.proto))
* The [src](../src) directory contains Stardoc's renderer, written in Java, which
transforms the proto output into Markdown.
* The [stardoc](../stardoc) directory contains the Starlark rule and wrapper
macro which serves as the entry point for Stardoc users, and the default
Velocity templates which configure Markdown output.
* Java unit tests live in the [src/test](../src/test/) directory, while
integration tests are in the [test](../test/) directory.

## Contributing to Stardoc

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ java_binary(
# ... but only on JDK >= 9
"-XX:+IgnoreUnrecognizedVMOptions",
],
main_class = "com.google.devtools.build.skydoc.renderer.RendererMain",
main_class = "com.google.devtools.build.stardoc.renderer.RendererMain",
visibility = ["//visibility:public"],
runtime_deps = [
":renderer_lib",
Expand All @@ -30,9 +30,8 @@ java_library(
name = "renderer_lib",
srcs = glob(["*.java"]),
deps = [
"//src/main/java/com/google/devtools/build/skydoc/rendering",
"//src/main/java/com/google/devtools/build/stardoc/rendering",
"//stardoc/proto:stardoc_output_java_proto",
"@com_google_protobuf//:protobuf_java",
"@stardoc_maven//:com_beust_jcommander",
"@stardoc_maven//:com_google_guava_guava",
],
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
// 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.skydoc.renderer;
package com.google.devtools.build.stardoc.renderer;

import java.io.FileOutputStream;
import java.io.IOException;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@
// 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.skydoc.renderer;
package com.google.devtools.build.stardoc.renderer;

import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos;
import java.io.FileOutputStream;
import java.io.IOException;

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.devtools.build.skydoc.renderer;
package com.google.devtools.build.stardoc.renderer;

import static com.google.common.collect.ImmutableList.toImmutableList;
import static java.nio.charset.StandardCharsets.UTF_8;
Expand All @@ -21,20 +21,18 @@
import com.beust.jcommander.JCommander;
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.MarkdownRenderer.Renderer;
import com.google.devtools.build.skydoc.rendering.Stamping;
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.ModuleExtensionInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.ModuleExtensionTagClassInfo;
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.RepositoryRuleInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.RuleInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.StarlarkFunctionInfo;
import com.google.protobuf.ExtensionRegistry;
import com.google.protobuf.InvalidProtocolBufferException;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.AspectInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.AttributeInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ModuleExtensionInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ModuleExtensionTagClassInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ModuleInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ProviderInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.RepositoryRuleInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.RuleInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.StarlarkFunctionInfo;
import com.google.devtools.build.stardoc.rendering.MarkdownRenderer;
import com.google.devtools.build.stardoc.rendering.MarkdownRenderer.Renderer;
import com.google.devtools.build.stardoc.rendering.Stamping;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.PrintWriter;
Expand Down Expand Up @@ -82,9 +80,7 @@ public void println() {
write("\n");
}
}) {
ModuleInfo moduleInfo =
ModuleInfo.parseFrom(
new FileInputStream(inputPath), ExtensionRegistry.getEmptyRegistry());
ModuleInfo moduleInfo = ModuleInfo.parseFrom(new FileInputStream(inputPath));

MarkdownRenderer renderer =
new MarkdownRenderer(
Expand Down Expand Up @@ -164,8 +160,14 @@ public void println() {
printWriter.println(renderer.renderMarkdownFooter(moduleInfo));
}

} catch (InvalidProtocolBufferException e) {
throw new IllegalArgumentException("Input file is not a valid ModuleInfo proto.", e);
} catch (IOException e) {
// Avoid an explicit dependency on the Java protobuf runtime as it should be injected by the
// root module via a proto_lang_toolchain.
if (e.getClass().getName().equals("com.google.protobuf.InvalidProtocolBufferException")) {
throw new IllegalArgumentException("Input file is not a valid ModuleInfo proto.", e);
} else {
throw e;
}
}
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.devtools.build.skydoc.renderer;
package com.google.devtools.build.stardoc.renderer;

import com.beust.jcommander.Parameter;
import com.beust.jcommander.Parameters;
Expand Down Expand Up @@ -80,9 +80,7 @@ class RendererOptions {
description = "The template for the documentation of a module extension")
String moduleExtensionTemplateFilePath;

@Parameter(
names = "--footer_template",
description = "The template for the footer string")
@Parameter(names = "--footer_template", description = "The template for the footer string")
String footerTemplateFilePath;

@Parameter(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,18 +12,18 @@
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.devtools.build.skydoc.rendering;
package com.google.devtools.build.stardoc.rendering;

import static java.nio.charset.StandardCharsets.UTF_8;

import com.google.common.collect.ImmutableMap;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.AspectInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.ModuleExtensionInfo;
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.RepositoryRuleInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.RuleInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.StarlarkFunctionInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.AspectInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ModuleExtensionInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ModuleInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ProviderInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.RepositoryRuleInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.RuleInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.StarlarkFunctionInfo;
import com.google.escapevelocity.EvaluationException;
import com.google.escapevelocity.ParseException;
import com.google.escapevelocity.Template;
Expand All @@ -38,7 +38,7 @@
import java.util.List;
import java.util.Optional;

/** Produces skydoc output in markdown form. */
/** Produces stardoc output in markdown form. */
public class MarkdownRenderer {

public interface Renderer<T> {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.devtools.build.skydoc.rendering;
package com.google.devtools.build.stardoc.rendering;

import static com.google.common.base.Strings.isNullOrEmpty;
import static com.google.common.collect.ImmutableList.toImmutableList;
Expand All @@ -21,18 +21,18 @@

import com.google.common.base.Joiner;
import com.google.common.collect.ImmutableList;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos;
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.AttributeType;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.FunctionParamInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.ModuleExtensionInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.ModuleExtensionTagClassInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.ProviderInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.ProviderNameGroup;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.RepositoryRuleInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.RuleInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.StarlarkFunctionInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.AspectInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.AttributeInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.AttributeType;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.FunctionParamInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ModuleExtensionInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ModuleExtensionTagClassInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ProviderFieldInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ProviderInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ProviderNameGroup;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.RepositoryRuleInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.RuleInfo;
import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.StarlarkFunctionInfo;
import java.time.Instant;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
Expand Down Expand Up @@ -231,7 +231,7 @@ public String ruleSummary(String ruleName, RuleInfo ruleInfo) {
public String providerSummary(String providerName, ProviderInfo providerInfo) {
ImmutableList<String> fieldNames =
providerInfo.getFieldInfoList().stream()
.map(StardocOutputProtos.ProviderFieldInfo::getName)
.map(ProviderFieldInfo::getName)
.collect(toImmutableList());
return maybeLoad(providerName) + summary(providerName, fieldNames);
}
Expand All @@ -254,8 +254,7 @@ public String aspectSummary(String aspectName, AspectInfo aspectInfo) {
.map(
file ->
String.format(
"# or on the command line:\n# --aspects=%s%%%s\n",
file, aspectName))
"# or on the command line:\n# --aspects=%s%%%s\n", file, aspectName))
.orElse("");
return maybeLoad(aspectName) + aspectFlag + summary(aspectName, attributeNames);
}
Expand Down Expand Up @@ -325,9 +324,7 @@ public String funcSummary(StarlarkFunctionInfo funcInfo) {

private String maybeLoad(String name) {
return entrypointBzlFile
.map(
file ->
String.format("load(\"%s\", \"%s\")\n", file, name.split("\\.")[0]))
.map(file -> String.format("load(\"%s\", \"%s\")\n", file, name.split("\\.")[0]))
.orElse("");
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.devtools.build.skydoc.rendering;
package com.google.devtools.build.stardoc.rendering;

import com.google.common.collect.ImmutableMap;
import java.io.IOException;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,12 +1,6 @@
load("@rules_java//java:defs.bzl", "java_test")

package(
default_applicable_licenses = ["//:license"],
default_visibility = [
"//src:__subpackages__",
"//stardoc:__subpackages__",
],
)
package(default_applicable_licenses = ["//:license"])

filegroup(
name = "srcs",
Expand All @@ -20,7 +14,7 @@ java_test(
size = "small",
srcs = ["MarkdownUtilTest.java"],
deps = [
"//src/main/java/com/google/devtools/build/skydoc/rendering",
"//src/main/java/com/google/devtools/build/stardoc/rendering",
"@stardoc_maven//:com_google_truth_truth",
"@stardoc_maven//:junit_junit",
],
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.devtools.build.skydoc.rendering;
package com.google.devtools.build.stardoc.rendering;

import static com.google.common.truth.Truth.assertThat;

Expand Down
Loading

0 comments on commit 67640b4

Please sign in to comment.