Sync Stardoc proto with Bazel tree and change "skydoc" in java packag…

…e names to "stardoc" (#222)

Sync stardoc_output.proto with bazel go get the updated Java package name in stardoc_output_java_proto

See bazelbuild/bazel@f4cfc84

BUILD

@@ -46,8 +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/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",

docs/advanced_stardoc_usage.md

@@ -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
@@ -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"`.

docs/contributing.md

@@ -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
 

src/main/java/com/google/devtools/build/skydoc/renderer/BUILD → src/main/java/com/google/devtools/build/stardoc/renderer/BUILD

@@ -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",
@@ -30,7 +30,7 @@ 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",
         "@stardoc_maven//:com_beust_jcommander",
         "@stardoc_maven//:com_google_guava_guava",

src/main/java/com/google/devtools/build/skydoc/renderer/FileSystemAccessor.java → src/main/java/com/google/devtools/build/stardoc/renderer/FileSystemAccessor.java

@@ -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;

src/main/java/com/google/devtools/build/skydoc/renderer/ProtoFileAccessor.java → src/main/java/com/google/devtools/build/stardoc/renderer/ProtoFileAccessor.java

@@ -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;
 

src/main/java/com/google/devtools/build/skydoc/renderer/RendererMain.java → src/main/java/com/google/devtools/build/stardoc/renderer/RendererMain.java

@@ -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;
@@ -21,18 +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.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;

src/main/java/com/google/devtools/build/skydoc/renderer/RendererOptions.java → src/main/java/com/google/devtools/build/stardoc/renderer/RendererOptions.java

@@ -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;
@@ -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(

src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownRenderer.java → src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownRenderer.java

@@ -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;
@@ -37,7 +37,7 @@
 import java.nio.file.Paths;
 import java.util.List;
 
-/** Produces skydoc output in markdown form. */
+/** Produces stardoc output in markdown form. */
 public class MarkdownRenderer {
 
   public interface Renderer<T> {

src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownUtil.java → src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownUtil.java

@@ -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;
@@ -21,17 +21,17 @@
 
 import com.google.common.base.Joiner;
 import com.google.common.collect.ImmutableList;
-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.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;

src/main/java/com/google/devtools/build/skydoc/rendering/Stamping.java → src/main/java/com/google/devtools/build/stardoc/rendering/Stamping.java

@@ -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;

src/test/java/com/google/devtools/build/skydoc/rendering/BUILD → src/test/java/com/google/devtools/build/stardoc/rendering/BUILD

@@ -14,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",
     ],

src/test/java/com/google/devtools/build/skydoc/rendering/MarkdownUtilTest.java → src/test/java/com/google/devtools/build/stardoc/rendering/MarkdownUtilTest.java

@@ -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;
 

stardoc/BUILD

@@ -51,7 +51,7 @@ stardoc(
 
 alias(
     name = "renderer",
-    actual = "//src/main/java/com/google/devtools/build/skydoc/renderer",
+    actual = "//src/main/java/com/google/devtools/build/stardoc/renderer",
 )
 
 # Sources needed for release tarball.

stardoc/proto/stardoc_output.proto

@@ -13,7 +13,7 @@
 // limitations under the License.
 //
 // Vendored from src/main/protobuf/stardoc_output.proto
-// in the Bazel source tree at commit 18a674ba8f92f2eaa7e4f66650a0f764f88f95adn
+// in the Bazel source tree at commit f4cfc846dbdf5f6c19d0a716fccd2ddcdae0d609n
 //
 // Protos for Stardoc data.
 //
@@ -23,7 +23,7 @@ syntax = "proto3";
 package stardoc_output;
 
 // option java_api_version = 2;
-option java_package = "com.google.devtools.build.skydoc.rendering.proto";
+option java_package = "com.google.devtools.build.lib.starlarkdocextract";
 option java_outer_classname = "StardocOutputProtos";
 
 // The root output proto of Stardoc. An invocation of Stardoc on a single file