Sync Stardoc proto with Bazel tree and change "skydoc" in java package names to "stardoc" (#222)
Sync stardoc_output.proto with bazel go get the updated Java package name in stardoc_output_java_proto
See https://github.com/bazelbuild/bazel/commit/f4cfc846dbdf5f6c19d0a716fccd2ddcdae0d609
diff --git a/BUILD b/BUILD
index 81db4cc..173fada 100644
--- a/BUILD
+++ b/BUILD
@@ -46,8 +46,8 @@
"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",
diff --git a/docs/advanced_stardoc_usage.md b/docs/advanced_stardoc_usage.md
index 6aa534b..bad4167 100644
--- a/docs/advanced_stardoc_usage.md
+++ b/docs/advanced_stardoc_usage.md
@@ -76,10 +76,11 @@
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 @@
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"`.
diff --git a/docs/contributing.md b/docs/contributing.md
index 0125737..004b5b1 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -15,16 +15,16 @@
## 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
diff --git a/src/main/java/com/google/devtools/build/skydoc/renderer/BUILD b/src/main/java/com/google/devtools/build/stardoc/renderer/BUILD
similarity index 86%
rename from src/main/java/com/google/devtools/build/skydoc/renderer/BUILD
rename to src/main/java/com/google/devtools/build/stardoc/renderer/BUILD
index 5ccec65..0b9d194 100644
--- a/src/main/java/com/google/devtools/build/skydoc/renderer/BUILD
+++ b/src/main/java/com/google/devtools/build/stardoc/renderer/BUILD
@@ -19,7 +19,7 @@
# ... 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 @@
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",
diff --git a/src/main/java/com/google/devtools/build/skydoc/renderer/FileSystemAccessor.java b/src/main/java/com/google/devtools/build/stardoc/renderer/FileSystemAccessor.java
similarity index 96%
rename from src/main/java/com/google/devtools/build/skydoc/renderer/FileSystemAccessor.java
rename to src/main/java/com/google/devtools/build/stardoc/renderer/FileSystemAccessor.java
index 3e424d8..437e0d5 100644
--- a/src/main/java/com/google/devtools/build/skydoc/renderer/FileSystemAccessor.java
+++ b/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;
diff --git a/src/main/java/com/google/devtools/build/skydoc/renderer/ProtoFileAccessor.java b/src/main/java/com/google/devtools/build/stardoc/renderer/ProtoFileAccessor.java
similarity index 92%
rename from src/main/java/com/google/devtools/build/skydoc/renderer/ProtoFileAccessor.java
rename to src/main/java/com/google/devtools/build/stardoc/renderer/ProtoFileAccessor.java
index 3b75d9b..2afab36 100644
--- a/src/main/java/com/google/devtools/build/skydoc/renderer/ProtoFileAccessor.java
+++ b/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;
diff --git a/src/main/java/com/google/devtools/build/skydoc/renderer/RendererMain.java b/src/main/java/com/google/devtools/build/stardoc/renderer/RendererMain.java
similarity index 92%
rename from src/main/java/com/google/devtools/build/skydoc/renderer/RendererMain.java
rename to src/main/java/com/google/devtools/build/stardoc/renderer/RendererMain.java
index c021d0c..6503e6f 100644
--- a/src/main/java/com/google/devtools/build/skydoc/renderer/RendererMain.java
+++ b/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;
diff --git a/src/main/java/com/google/devtools/build/skydoc/renderer/RendererOptions.java b/src/main/java/com/google/devtools/build/stardoc/renderer/RendererOptions.java
similarity index 94%
rename from src/main/java/com/google/devtools/build/skydoc/renderer/RendererOptions.java
rename to src/main/java/com/google/devtools/build/stardoc/renderer/RendererOptions.java
index 74d6975..7f770fd 100644
--- a/src/main/java/com/google/devtools/build/skydoc/renderer/RendererOptions.java
+++ b/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 @@
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(
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/BUILD b/src/main/java/com/google/devtools/build/stardoc/rendering/BUILD
similarity index 100%
rename from src/main/java/com/google/devtools/build/skydoc/rendering/BUILD
rename to src/main/java/com/google/devtools/build/stardoc/rendering/BUILD
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownRenderer.java b/src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownRenderer.java
similarity index 94%
rename from src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownRenderer.java
rename to src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownRenderer.java
index 03b45d4..991378c 100644
--- a/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownRenderer.java
+++ b/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> {
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownUtil.java b/src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownUtil.java
similarity index 95%
rename from src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownUtil.java
rename to src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownUtil.java
index 4ddce0f..acde9ae 100644
--- a/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownUtil.java
+++ b/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;
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/Stamping.java b/src/main/java/com/google/devtools/build/stardoc/rendering/Stamping.java
similarity index 97%
rename from src/main/java/com/google/devtools/build/skydoc/rendering/Stamping.java
rename to src/main/java/com/google/devtools/build/stardoc/rendering/Stamping.java
index 2da4eb5..ce4859f 100644
--- a/src/main/java/com/google/devtools/build/skydoc/rendering/Stamping.java
+++ b/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;
diff --git a/src/test/java/com/google/devtools/build/skydoc/rendering/BUILD b/src/test/java/com/google/devtools/build/stardoc/rendering/BUILD
similarity index 85%
rename from src/test/java/com/google/devtools/build/skydoc/rendering/BUILD
rename to src/test/java/com/google/devtools/build/stardoc/rendering/BUILD
index fdbba70..771750f 100644
--- a/src/test/java/com/google/devtools/build/skydoc/rendering/BUILD
+++ b/src/test/java/com/google/devtools/build/stardoc/rendering/BUILD
@@ -14,7 +14,7 @@
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",
],
diff --git a/src/test/java/com/google/devtools/build/skydoc/rendering/MarkdownUtilTest.java b/src/test/java/com/google/devtools/build/stardoc/rendering/MarkdownUtilTest.java
similarity index 98%
rename from src/test/java/com/google/devtools/build/skydoc/rendering/MarkdownUtilTest.java
rename to src/test/java/com/google/devtools/build/stardoc/rendering/MarkdownUtilTest.java
index 4c37a38..82fdfad 100644
--- a/src/test/java/com/google/devtools/build/skydoc/rendering/MarkdownUtilTest.java
+++ b/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;
diff --git a/stardoc/BUILD b/stardoc/BUILD
index 8700982..5e91a06 100644
--- a/stardoc/BUILD
+++ b/stardoc/BUILD
@@ -51,7 +51,7 @@
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.
diff --git a/stardoc/proto/stardoc_output.proto b/stardoc/proto/stardoc_output.proto
index 8b3ee96..82c97e8 100644
--- a/stardoc/proto/stardoc_output.proto
+++ b/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 @@
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
