Remove legacy bundled extractor jar and its usage; require starlark_doc_extract (#212)
diff --git a/MODULE.bazel b/MODULE.bazel
index 1363204..6fdafe5 100644
--- a/MODULE.bazel
+++ b/MODULE.bazel
@@ -1,6 +1,6 @@
module(
name = "stardoc",
- version = "0.6.2",
+ version = "0.7.0-pre",
compatibility_level = 1,
)
diff --git a/WORKSPACE b/WORKSPACE
index c3b8f4a..2031dab 100644
--- a/WORKSPACE
+++ b/WORKSPACE
@@ -38,50 +38,6 @@
remote = "https://github.com/bazelbuild/bazel.git",
)
-load("@rules_jvm_external//:defs.bzl", "maven_install")
-
-# Bazel's Maven dependencies - must live in @maven
-maven_install(
- artifacts = [
- "com.github.ben-manes.caffeine:caffeine:3.0.5",
- "com.github.stephenc.jcip:jcip-annotations:1.0-1",
- "com.google.auto.service:auto-service-annotations:1.0.1",
- "com.google.auto.service:auto-service:1.0",
- "com.google.auto.value:auto-value-annotations:1.9",
- "com.google.auto.value:auto-value:1.8.2",
- "com.google.auto:auto-common:1.2.1",
- "com.google.code.findbugs:jsr305:3.0.2",
- "com.google.code.gson:gson:2.9.0",
- "com.google.errorprone:error_prone_annotations:2.18.0",
- "com.google.errorprone:error_prone_type_annotations:2.18.0",
- "com.google.flogger:flogger-system-backend:0.5.1",
- "com.google.flogger:flogger:0.5.1",
- "com.google.flogger:google-extensions:0.5.1",
- "com.google.guava:failureaccess:1.0.1",
- "com.google.guava:guava:31.1-jre",
- "com.google.j2objc:j2objc-annotations:1.3",
- "com.ryanharter.auto.value:auto-value-gson-extension:1.3.1",
- "com.ryanharter.auto.value:auto-value-gson-runtime:1.3.1",
- "com.ryanharter.auto.value:auto-value-gson-factory:1.3.1",
- "com.squareup:javapoet:1.12.0",
- "commons-collections:commons-collections:3.2.2",
- "commons-lang:commons-lang:2.6",
- "org.apache.tomcat:tomcat-annotations-api:8.0.5",
- "org.apache.velocity:velocity:1.7",
- "org.checkerframework:checker-qual:3.19.0",
- ],
- fail_if_repin_required = True,
- maven_install_json = "//:legacy_maven_install.json",
- repositories = [
- "https://repo1.maven.org/maven2",
- ],
- strict_visibility = True,
-)
-
-load("@maven//:defs.bzl", "pinned_maven_install")
-
-pinned_maven_install()
-
# The following binds are needed for building protobuf java libraries.
bind(
name = "guava",
@@ -98,26 +54,7 @@
actual = "@io_bazel//third_party:error_prone_annotations",
)
-# Needed only because of java_tools.
-http_archive(
- name = "rules_cc",
- sha256 = "36fa66d4d49debd71d05fba55c1353b522e8caef4a20f8080a3d17cdda001d89",
- strip_prefix = "rules_cc-0d5f3f2768c6ca2faca0079a997a97ce22997a0c",
- urls = [
- "https://mirror.bazel.build/github.com/bazelbuild/rules_cc/archive/0d5f3f2768c6ca2faca0079a997a97ce22997a0c.zip",
- "https://github.com/bazelbuild/rules_cc/archive/0d5f3f2768c6ca2faca0079a997a97ce22997a0c.zip",
- ],
-)
-
-# Needed as a transitive dependency of @io_bazel
-http_archive(
- name = "rules_python",
- sha256 = "a644da969b6824cc87f8fe7b18101a8a6c57da5db39caa6566ec6109f37d2141",
- strip_prefix = "rules_python-0.20.0",
- urls = ["https://github.com/bazelbuild/rules_python/releases/download/0.20.0/rules_python-0.20.0.tar.gz"],
-)
-
-# Needed for //distro:__pkg__ and as a transitive dependency of @io_bazel
+# Needed for //distro:__pkg__
http_archive(
name = "rules_pkg",
sha256 = "eea0f59c28a9241156a47d7a8e32db9122f3d50b505fae0f33de6ce4d9b61834",
@@ -152,14 +89,3 @@
rules_proto_dependencies()
rules_proto_toolchains()
-
-# Needed as a transitive dependency of @io_bazel
-http_archive(
- name = "blake3",
- build_file = "@io_bazel//third_party:blake3/blake3.BUILD",
- sha256 = "bb529ba133c0256df49139bd403c17835edbf60d2ecd6463549c6a5fe279364d",
- strip_prefix = "BLAKE3-1.3.3",
- urls = [
- "https://github.com/BLAKE3-team/BLAKE3/archive/refs/tags/1.3.3.zip",
- ],
-)
diff --git a/docs/maintainers_guide.md b/docs/maintainers_guide.md
index 1e271a5..d73fbb3 100644
--- a/docs/maintainers_guide.md
+++ b/docs/maintainers_guide.md
@@ -1,28 +1,20 @@
# Stardoc Maintainer's Guide
-## Updating Proto and Bundled Jar
+## Updating Proto
Stardoc proto definition is vendored from the Bazel source tree at
-https://github.com/bazelbuild/bazel/tree/master/src/main/java/com/google/devtools/build/skydoc/rendering/proto/stardoc_output.proto
+https://github.com/bazelbuild/bazel/tree/master/src/main/protobuf/stardoc_output.proto
-Stardoc legacy extractor's source code lives in the Bazel source tree at
-https://github.com/bazelbuild/bazel/tree/master/src/main/java/com/google/devtools/build/skydoc
+To update the proto definition from Bazel's master branch, run
+`update-release-binary.sh`
-For simplicity of use and building, Stardoc bundles a pre-built jar for the
-legacy extractor which is built from Bazel source: `stardoc_binary.jar`
-(emits protobuf documentation format).
-
-To update the proto definition and jar:
-
-1. Update `io_bazel` repo commit in `WORKSPACE`. Update transitive deps in
- `WORKSPACE` as needed.
-2. run `update-release-binary.sh`
+To vendor the proto definition from a particular branch or commit in the Bazel
+tree, run `BAZEL_BRANCH=$BRANCH_OR_SHA ./update-release-binary.sh`
## Making a New Release
1. Verify tests. Verify that dependencies are consistent between `setup.bzl` +
- `WORKSPACE` and `MODULE.bazel` (but note that `MODULE.bazel` does not
- include dependencies on `io_bazel` and its transitive deps).
+ `WORKSPACE` and `MODULE.bazel`.
2. Update `CHANGELOG.md` at the top. You may want to use the following \
template:
diff --git a/docs/stardoc_rule.md b/docs/stardoc_rule.md
index cb01469..be570a8 100644
--- a/docs/stardoc_rule.md
+++ b/docs/stardoc_rule.md
@@ -7,10 +7,10 @@
## stardoc
<pre>
-stardoc(<a href="#stardoc-name">name</a>, <a href="#stardoc-input">input</a>, <a href="#stardoc-out">out</a>, <a href="#stardoc-deps">deps</a>, <a href="#stardoc-format">format</a>, <a href="#stardoc-symbol_names">symbol_names</a>, <a href="#stardoc-semantic_flags">semantic_flags</a>, <a href="#stardoc-stardoc">stardoc</a>, <a href="#stardoc-renderer">renderer</a>,
- <a href="#stardoc-aspect_template">aspect_template</a>, <a href="#stardoc-func_template">func_template</a>, <a href="#stardoc-header_template">header_template</a>, <a href="#stardoc-table_of_contents_template">table_of_contents_template</a>,
- <a href="#stardoc-provider_template">provider_template</a>, <a href="#stardoc-rule_template">rule_template</a>, <a href="#stardoc-repository_rule_template">repository_rule_template</a>, <a href="#stardoc-module_extension_template">module_extension_template</a>,
- <a href="#stardoc-footer_template">footer_template</a>, <a href="#stardoc-use_starlark_doc_extract">use_starlark_doc_extract</a>, <a href="#stardoc-render_main_repo_name">render_main_repo_name</a>, <a href="#stardoc-stamp">stamp</a>, <a href="#stardoc-kwargs">kwargs</a>)
+stardoc(<a href="#stardoc-name">name</a>, <a href="#stardoc-input">input</a>, <a href="#stardoc-out">out</a>, <a href="#stardoc-deps">deps</a>, <a href="#stardoc-format">format</a>, <a href="#stardoc-symbol_names">symbol_names</a>, <a href="#stardoc-renderer">renderer</a>, <a href="#stardoc-aspect_template">aspect_template</a>, <a href="#stardoc-func_template">func_template</a>,
+ <a href="#stardoc-header_template">header_template</a>, <a href="#stardoc-table_of_contents_template">table_of_contents_template</a>, <a href="#stardoc-provider_template">provider_template</a>, <a href="#stardoc-rule_template">rule_template</a>,
+ <a href="#stardoc-repository_rule_template">repository_rule_template</a>, <a href="#stardoc-module_extension_template">module_extension_template</a>, <a href="#stardoc-footer_template">footer_template</a>, <a href="#stardoc-render_main_repo_name">render_main_repo_name</a>,
+ <a href="#stardoc-stamp">stamp</a>, <a href="#stardoc-kwargs">kwargs</a>)
</pre>
Generates documentation for exported starlark rule definitions in a target starlark file.
@@ -26,8 +26,6 @@
| <a id="stardoc-deps"></a>deps | A list of bzl_library dependencies which the input depends on. | `[]` |
| <a id="stardoc-format"></a>format | The format of the output file. Valid values: 'markdown' or 'proto'. | `"markdown"` |
| <a id="stardoc-symbol_names"></a>symbol_names | A list of symbol names to generate documentation for. These should correspond to the names of rule definitions in the input file. If this list is empty, then documentation for all exported rule definitions will be generated. | `[]` |
-| <a id="stardoc-semantic_flags"></a>semantic_flags | A list of canonical flags to affect Starlark semantics for the Starlark interpreter during documentation generation. This should only be used to maintain compatibility with non-default semantic flags required to use the given Starlark symbols.<br><br>For example, if `//foo:bar.bzl` does not build except when a user would specify `--incompatible_foo_semantic=false`, then this attribute should contain "--incompatible_foo_semantic=false". | `[]` |
-| <a id="stardoc-stardoc"></a>stardoc | The location of the legacy Stardoc extractor. Ignored when using the native `starlark_doc_extract` rule. | `Label("@io_bazel_stardoc//stardoc:prebuilt_stardoc_binary")` |
| <a id="stardoc-renderer"></a>renderer | The location of the renderer tool. | `Label("@io_bazel_stardoc//stardoc:renderer")` |
| <a id="stardoc-aspect_template"></a>aspect_template | The input file template for generating documentation of aspects | `Label("@io_bazel_stardoc//stardoc:templates/markdown_tables/aspect.vm")` |
| <a id="stardoc-func_template"></a>func_template | The input file template for generating documentation of functions. | `Label("@io_bazel_stardoc//stardoc:templates/markdown_tables/func.vm")` |
@@ -35,11 +33,10 @@
| <a id="stardoc-table_of_contents_template"></a>table_of_contents_template | The input file template for the table of contents of the output documentation. This is unset by default for backwards compatibility. Use `Label("@stardoc//stardoc:templates/markdown_tables/table_of_contents.vm")` for the default template. | `None` |
| <a id="stardoc-provider_template"></a>provider_template | The input file template for generating documentation of providers. | `Label("@io_bazel_stardoc//stardoc:templates/markdown_tables/provider.vm")` |
| <a id="stardoc-rule_template"></a>rule_template | The input file template for generating documentation of rules. | `Label("@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm")` |
-| <a id="stardoc-repository_rule_template"></a>repository_rule_template | The input file template for generating documentation of repository rules. This template is used only when using the native `starlark_doc_extract` rule. | `Label("@io_bazel_stardoc//stardoc:templates/markdown_tables/repository_rule.vm")` |
-| <a id="stardoc-module_extension_template"></a>module_extension_template | The input file template for generating documentation of module extensions. This template is used only when using the native `starlark_doc_extract` rule. | `Label("@io_bazel_stardoc//stardoc:templates/markdown_tables/module_extension.vm")` |
+| <a id="stardoc-repository_rule_template"></a>repository_rule_template | The input file template for generating documentation of repository rules. | `Label("@io_bazel_stardoc//stardoc:templates/markdown_tables/repository_rule.vm")` |
+| <a id="stardoc-module_extension_template"></a>module_extension_template | The input file template for generating documentation of module extensions. | `Label("@io_bazel_stardoc//stardoc:templates/markdown_tables/module_extension.vm")` |
| <a id="stardoc-footer_template"></a>footer_template | The input file template for generating the footer of the output documentation. Optional. | `None` |
-| <a id="stardoc-use_starlark_doc_extract"></a>use_starlark_doc_extract | Use the native `starlark_doc_extract` rule if available. | `True` |
-| <a id="stardoc-render_main_repo_name"></a>render_main_repo_name | Render labels in the main repository with a repo component (either the module name or workspace name). This parameter is used only when using the native `starlark_doc_extract` rule. | `True` |
+| <a id="stardoc-render_main_repo_name"></a>render_main_repo_name | Render labels in the main repository with a repo component (either the module name or workspace name). | `True` |
| <a id="stardoc-stamp"></a>stamp | Whether to provide stamping information to templates. | `False` |
| <a id="stardoc-kwargs"></a>kwargs | Further arguments to pass to stardoc. | none |
diff --git a/legacy_maven_install.json b/legacy_maven_install.json
deleted file mode 100644
index c3f8dab..0000000
--- a/legacy_maven_install.json
+++ /dev/null
@@ -1,529 +0,0 @@
-{
- "__AUTOGENERATED_FILE_DO_NOT_MODIFY_THIS_FILE_MANUALLY": "THERE_IS_NO_DATA_ONLY_ZUUL",
- "__INPUT_ARTIFACTS_HASH": 1429940565,
- "__RESOLVED_ARTIFACTS_HASH": -1447515200,
- "artifacts": {
- "com.github.ben-manes.caffeine:caffeine": {
- "shasums": {
- "jar": "8a9b54d3506a3b92ee46b217bcee79196b21ca6d52dc2967c686a205fb2f9c15"
- },
- "version": "3.0.5"
- },
- "com.github.stephenc.jcip:jcip-annotations": {
- "shasums": {
- "jar": "4fccff8382aafc589962c4edb262f6aa595e34f1e11e61057d1c6a96e8fc7323"
- },
- "version": "1.0-1"
- },
- "com.google.auto.service:auto-service": {
- "shasums": {
- "jar": "4ae44dd05b49a1109a463c0d2aaf920c24f76d1e996bb89f29481c4ff75ec526"
- },
- "version": "1.0"
- },
- "com.google.auto.service:auto-service-annotations": {
- "shasums": {
- "jar": "c7bec54b7b5588b5967e870341091c5691181d954cf2039f1bf0a6eeb837473b"
- },
- "version": "1.0.1"
- },
- "com.google.auto.value:auto-value": {
- "shasums": {
- "jar": "2067b788d4c1c96fd621ad861053a5c4d8a801cfafc77fec20d49a6e9340a745"
- },
- "version": "1.8.2"
- },
- "com.google.auto.value:auto-value-annotations": {
- "shasums": {
- "jar": "fa5469f4c44ee598a2d8f033ab0a9dcbc6498a0c5e0c998dfa0c2adf51358044"
- },
- "version": "1.9"
- },
- "com.google.auto:auto-common": {
- "shasums": {
- "jar": "f43f29fe2a6ebaf04b2598cdeec32a4e346d49a9404e990f5fc19c19f3a28d0e"
- },
- "version": "1.2.1"
- },
- "com.google.code.findbugs:jsr305": {
- "shasums": {
- "jar": "766ad2a0783f2687962c8ad74ceecc38a28b9f72a2d085ee438b7813e928d0c7"
- },
- "version": "3.0.2"
- },
- "com.google.code.gson:gson": {
- "shasums": {
- "jar": "c96d60551331a196dac54b745aa642cd078ef89b6f267146b705f2c2cbef052d"
- },
- "version": "2.9.0"
- },
- "com.google.errorprone:error_prone_annotations": {
- "shasums": {
- "jar": "9e6814cb71816988a4fd1b07a993a8f21bb7058d522c162b1de849e19bea54ae"
- },
- "version": "2.18.0"
- },
- "com.google.errorprone:error_prone_type_annotations": {
- "shasums": {
- "jar": "d2ab73bc6807277f7463391504313e47bc3465ab1916339c8e82be633a9ab375"
- },
- "version": "2.18.0"
- },
- "com.google.flogger:flogger": {
- "shasums": {
- "jar": "b5ecd1483e041197012786f749968a62063c1964d3ecfbf96ba92a95797bb8f5"
- },
- "version": "0.5.1"
- },
- "com.google.flogger:flogger-system-backend": {
- "shasums": {
- "jar": "685de33b53eb313049bbeee7f4b7a80dd09e8e754e96b048a3edab2cebb36442"
- },
- "version": "0.5.1"
- },
- "com.google.flogger:google-extensions": {
- "shasums": {
- "jar": "8b0862cad85b9549f355fe383c6c63816d2f19529634e033ae06d0107ab110b9"
- },
- "version": "0.5.1"
- },
- "com.google.guava:failureaccess": {
- "shasums": {
- "jar": "a171ee4c734dd2da837e4b16be9df4661afab72a41adaf31eb84dfdaf936ca26"
- },
- "version": "1.0.1"
- },
- "com.google.guava:guava": {
- "shasums": {
- "jar": "a42edc9cab792e39fe39bb94f3fca655ed157ff87a8af78e1d6ba5b07c4a00ab"
- },
- "version": "31.1-jre"
- },
- "com.google.guava:listenablefuture": {
- "shasums": {
- "jar": "b372a037d4230aa57fbeffdef30fd6123f9c0c2db85d0aced00c91b974f33f99"
- },
- "version": "9999.0-empty-to-avoid-conflict-with-guava"
- },
- "com.google.j2objc:j2objc-annotations": {
- "shasums": {
- "jar": "21af30c92267bd6122c0e0b4d20cccb6641a37eaf956c6540ec471d584e64a7b"
- },
- "version": "1.3"
- },
- "com.ryanharter.auto.value:auto-value-gson-extension": {
- "shasums": {
- "jar": "261be84be30a56994e132d718a85efcd579197a2edb9426b84c5722c56955eca"
- },
- "version": "1.3.1"
- },
- "com.ryanharter.auto.value:auto-value-gson-factory": {
- "shasums": {
- "jar": "5a76c3d401c984999d59868f08df05a15613d1428f7764fed80b722e2a277f6c"
- },
- "version": "1.3.1"
- },
- "com.ryanharter.auto.value:auto-value-gson-runtime": {
- "shasums": {
- "jar": "84ee23b7989d4bf19930b5bd3d03c0f2efb9e73bcee3a0208a9d1b2e1979c049"
- },
- "version": "1.3.1"
- },
- "com.squareup:javapoet": {
- "shasums": {
- "jar": "2b70cdfa8c9e997b4007035a266c273c0df341f9c57c9d0b45a680ae3fd882db"
- },
- "version": "1.12.0"
- },
- "commons-collections:commons-collections": {
- "shasums": {
- "jar": "eeeae917917144a68a741d4c0dff66aa5c5c5fd85593ff217bced3fc8ca783b8"
- },
- "version": "3.2.2"
- },
- "commons-lang:commons-lang": {
- "shasums": {
- "jar": "50f11b09f877c294d56f24463f47d28f929cf5044f648661c0f0cfbae9a2f49c"
- },
- "version": "2.6"
- },
- "io.sweers.autotransient:autotransient": {
- "shasums": {
- "jar": "914ce84508410ee1419514925f93b1855a9f7a7b5b5d02fc07f411d2a45f1bba"
- },
- "version": "1.0.0"
- },
- "org.apache.tomcat:tomcat-annotations-api": {
- "shasums": {
- "jar": "748677bebb1651a313317dfd93e984ed8f8c9e345538fa8b0ab0cbb804631953"
- },
- "version": "8.0.5"
- },
- "org.apache.velocity:velocity": {
- "shasums": {
- "jar": "ec92dae810034f4b46dbb16ef4364a4013b0efb24a8c5dd67435cae46a290d8e"
- },
- "version": "1.7"
- },
- "org.checkerframework:checker-compat-qual": {
- "shasums": {
- "jar": "d76b9afea61c7c082908023f0cbc1427fab9abd2df915c8b8a3e7a509bccbc6d"
- },
- "version": "2.5.3"
- },
- "org.checkerframework:checker-qual": {
- "shasums": {
- "jar": "a827c49183f3a632277d27a0a4673686cb341507447b9d570261094bd748aa68"
- },
- "version": "3.19.0"
- }
- },
- "dependencies": {
- "com.github.ben-manes.caffeine:caffeine": [
- "com.google.errorprone:error_prone_annotations",
- "org.checkerframework:checker-qual"
- ],
- "com.google.auto.service:auto-service": [
- "com.google.auto.service:auto-service-annotations",
- "com.google.auto:auto-common",
- "com.google.guava:guava"
- ],
- "com.google.auto:auto-common": [
- "com.google.guava:guava"
- ],
- "com.google.flogger:flogger": [
- "org.checkerframework:checker-compat-qual"
- ],
- "com.google.flogger:flogger-system-backend": [
- "com.google.flogger:flogger",
- "org.checkerframework:checker-compat-qual"
- ],
- "com.google.flogger:google-extensions": [
- "com.google.flogger:flogger"
- ],
- "com.google.guava:guava": [
- "com.google.code.findbugs:jsr305",
- "com.google.errorprone:error_prone_annotations",
- "com.google.guava:failureaccess",
- "com.google.guava:listenablefuture",
- "com.google.j2objc:j2objc-annotations",
- "org.checkerframework:checker-qual"
- ],
- "com.ryanharter.auto.value:auto-value-gson-extension": [
- "com.google.auto.value:auto-value",
- "com.google.auto.value:auto-value-annotations",
- "com.google.code.gson:gson",
- "com.ryanharter.auto.value:auto-value-gson-runtime",
- "com.squareup:javapoet"
- ],
- "com.ryanharter.auto.value:auto-value-gson-factory": [
- "com.google.auto.value:auto-value-annotations",
- "com.google.code.gson:gson",
- "com.ryanharter.auto.value:auto-value-gson-extension",
- "com.squareup:javapoet"
- ],
- "com.ryanharter.auto.value:auto-value-gson-runtime": [
- "com.google.code.gson:gson",
- "io.sweers.autotransient:autotransient"
- ],
- "org.apache.velocity:velocity": [
- "commons-collections:commons-collections",
- "commons-lang:commons-lang"
- ]
- },
- "packages": {
- "com.github.ben-manes.caffeine:caffeine": [
- "com.github.benmanes.caffeine.cache",
- "com.github.benmanes.caffeine.cache.stats"
- ],
- "com.github.stephenc.jcip:jcip-annotations": [
- "net.jcip.annotations"
- ],
- "com.google.auto.service:auto-service": [
- "com.google.auto.service.processor"
- ],
- "com.google.auto.service:auto-service-annotations": [
- "com.google.auto.service"
- ],
- "com.google.auto.value:auto-value": [
- "autovalue.shaded.com.google$.auto.common",
- "autovalue.shaded.com.google$.auto.service",
- "autovalue.shaded.com.google$.common.annotations",
- "autovalue.shaded.com.google$.common.base",
- "autovalue.shaded.com.google$.common.collect",
- "autovalue.shaded.com.google$.common.hash",
- "autovalue.shaded.com.google$.common.math",
- "autovalue.shaded.com.google$.common.primitives",
- "autovalue.shaded.com.google$.common.reflect",
- "autovalue.shaded.com.google$.errorprone.annotations",
- "autovalue.shaded.com.google$.errorprone.annotations.concurrent",
- "autovalue.shaded.com.google$.escapevelocity",
- "autovalue.shaded.com.google$.j2objc.annotations",
- "autovalue.shaded.com.squareup.javapoet$",
- "autovalue.shaded.net.ltgt.gradle.incap$",
- "autovalue.shaded.org.checkerframework$.checker.nullness.qual",
- "autovalue.shaded.org.checkerframework$.framework.qual",
- "com.google.auto.value.extension",
- "com.google.auto.value.extension.memoized.processor",
- "com.google.auto.value.extension.serializable.processor",
- "com.google.auto.value.extension.serializable.serializer",
- "com.google.auto.value.extension.serializable.serializer.impl",
- "com.google.auto.value.extension.serializable.serializer.interfaces",
- "com.google.auto.value.extension.serializable.serializer.runtime",
- "com.google.auto.value.extension.toprettystring.processor",
- "com.google.auto.value.processor"
- ],
- "com.google.auto.value:auto-value-annotations": [
- "com.google.auto.value",
- "com.google.auto.value.extension.memoized",
- "com.google.auto.value.extension.serializable",
- "com.google.auto.value.extension.toprettystring"
- ],
- "com.google.auto:auto-common": [
- "com.google.auto.common"
- ],
- "com.google.code.findbugs:jsr305": [
- "javax.annotation",
- "javax.annotation.concurrent",
- "javax.annotation.meta"
- ],
- "com.google.code.gson:gson": [
- "com.google.gson",
- "com.google.gson.annotations",
- "com.google.gson.internal",
- "com.google.gson.internal.bind",
- "com.google.gson.internal.bind.util",
- "com.google.gson.internal.reflect",
- "com.google.gson.internal.sql",
- "com.google.gson.reflect",
- "com.google.gson.stream"
- ],
- "com.google.errorprone:error_prone_annotations": [
- "com.google.errorprone.annotations",
- "com.google.errorprone.annotations.concurrent"
- ],
- "com.google.errorprone:error_prone_type_annotations": [
- "com.google.errorprone.annotations"
- ],
- "com.google.flogger:flogger": [
- "com.google.common.flogger",
- "com.google.common.flogger.backend",
- "com.google.common.flogger.context",
- "com.google.common.flogger.parameter",
- "com.google.common.flogger.parser",
- "com.google.common.flogger.util"
- ],
- "com.google.flogger:flogger-system-backend": [
- "com.google.common.flogger.backend.system"
- ],
- "com.google.flogger:google-extensions": [
- "com.google.common.flogger"
- ],
- "com.google.guava:failureaccess": [
- "com.google.common.util.concurrent.internal"
- ],
- "com.google.guava:guava": [
- "com.google.common.annotations",
- "com.google.common.base",
- "com.google.common.base.internal",
- "com.google.common.cache",
- "com.google.common.collect",
- "com.google.common.escape",
- "com.google.common.eventbus",
- "com.google.common.graph",
- "com.google.common.hash",
- "com.google.common.html",
- "com.google.common.io",
- "com.google.common.math",
- "com.google.common.net",
- "com.google.common.primitives",
- "com.google.common.reflect",
- "com.google.common.util.concurrent",
- "com.google.common.xml",
- "com.google.thirdparty.publicsuffix"
- ],
- "com.google.j2objc:j2objc-annotations": [
- "com.google.j2objc.annotations"
- ],
- "com.ryanharter.auto.value:auto-value-gson-extension": [
- "autovaluegson.shaded.com.google.auto.common",
- "autovaluegson.shaded.com.google.common.annotations",
- "autovaluegson.shaded.com.google.common.base",
- "autovaluegson.shaded.com.google.common.cache",
- "autovaluegson.shaded.com.google.common.collect",
- "autovaluegson.shaded.com.google.common.escape",
- "autovaluegson.shaded.com.google.common.eventbus",
- "autovaluegson.shaded.com.google.common.graph",
- "autovaluegson.shaded.com.google.common.hash",
- "autovaluegson.shaded.com.google.common.html",
- "autovaluegson.shaded.com.google.common.io",
- "autovaluegson.shaded.com.google.common.math",
- "autovaluegson.shaded.com.google.common.net",
- "autovaluegson.shaded.com.google.common.primitives",
- "autovaluegson.shaded.com.google.common.reflect",
- "autovaluegson.shaded.com.google.common.util.concurrent",
- "autovaluegson.shaded.com.google.common.xml",
- "com.ryanharter.auto.value.gson"
- ],
- "com.ryanharter.auto.value:auto-value-gson-factory": [
- "autovaluegson.factory.shaded.com.google.auto.common",
- "autovaluegson.factory.shaded.com.google.common.annotations",
- "autovaluegson.factory.shaded.com.google.common.base",
- "autovaluegson.factory.shaded.com.google.common.cache",
- "autovaluegson.factory.shaded.com.google.common.collect",
- "autovaluegson.factory.shaded.com.google.common.escape",
- "autovaluegson.factory.shaded.com.google.common.eventbus",
- "autovaluegson.factory.shaded.com.google.common.graph",
- "autovaluegson.factory.shaded.com.google.common.hash",
- "autovaluegson.factory.shaded.com.google.common.html",
- "autovaluegson.factory.shaded.com.google.common.io",
- "autovaluegson.factory.shaded.com.google.common.math",
- "autovaluegson.factory.shaded.com.google.common.net",
- "autovaluegson.factory.shaded.com.google.common.primitives",
- "autovaluegson.factory.shaded.com.google.common.reflect",
- "autovaluegson.factory.shaded.com.google.common.util.concurrent",
- "autovaluegson.factory.shaded.com.google.common.xml",
- "com.ryanharter.auto.value.gson.factory"
- ],
- "com.ryanharter.auto.value:auto-value-gson-runtime": [
- "com.ryanharter.auto.value.gson",
- "com.ryanharter.auto.value.gson.internal"
- ],
- "com.squareup:javapoet": [
- "com.squareup.javapoet"
- ],
- "commons-collections:commons-collections": [
- "org.apache.commons.collections",
- "org.apache.commons.collections.bag",
- "org.apache.commons.collections.bidimap",
- "org.apache.commons.collections.buffer",
- "org.apache.commons.collections.collection",
- "org.apache.commons.collections.comparators",
- "org.apache.commons.collections.functors",
- "org.apache.commons.collections.iterators",
- "org.apache.commons.collections.keyvalue",
- "org.apache.commons.collections.list",
- "org.apache.commons.collections.map",
- "org.apache.commons.collections.set"
- ],
- "commons-lang:commons-lang": [
- "org.apache.commons.lang",
- "org.apache.commons.lang.builder",
- "org.apache.commons.lang.enum",
- "org.apache.commons.lang.enums",
- "org.apache.commons.lang.exception",
- "org.apache.commons.lang.math",
- "org.apache.commons.lang.mutable",
- "org.apache.commons.lang.reflect",
- "org.apache.commons.lang.text",
- "org.apache.commons.lang.time"
- ],
- "io.sweers.autotransient:autotransient": [
- "io.sweers.autotransient"
- ],
- "org.apache.tomcat:tomcat-annotations-api": [
- "javax.annotation",
- "javax.annotation.security",
- "javax.annotation.sql",
- "javax.ejb",
- "javax.persistence",
- "javax.xml.ws"
- ],
- "org.apache.velocity:velocity": [
- "org.apache.velocity",
- "org.apache.velocity.anakia",
- "org.apache.velocity.app",
- "org.apache.velocity.app.event",
- "org.apache.velocity.app.event.implement",
- "org.apache.velocity.app.tools",
- "org.apache.velocity.context",
- "org.apache.velocity.convert",
- "org.apache.velocity.exception",
- "org.apache.velocity.io",
- "org.apache.velocity.runtime",
- "org.apache.velocity.runtime.directive",
- "org.apache.velocity.runtime.log",
- "org.apache.velocity.runtime.parser",
- "org.apache.velocity.runtime.parser.node",
- "org.apache.velocity.runtime.resource",
- "org.apache.velocity.runtime.resource.loader",
- "org.apache.velocity.runtime.resource.util",
- "org.apache.velocity.runtime.visitor",
- "org.apache.velocity.servlet",
- "org.apache.velocity.texen",
- "org.apache.velocity.texen.ant",
- "org.apache.velocity.texen.util",
- "org.apache.velocity.util",
- "org.apache.velocity.util.introspection"
- ],
- "org.checkerframework:checker-compat-qual": [
- "org.checkerframework.checker.nullness.compatqual"
- ],
- "org.checkerframework:checker-qual": [
- "org.checkerframework.checker.builder.qual",
- "org.checkerframework.checker.calledmethods.qual",
- "org.checkerframework.checker.compilermsgs.qual",
- "org.checkerframework.checker.fenum.qual",
- "org.checkerframework.checker.formatter.qual",
- "org.checkerframework.checker.guieffect.qual",
- "org.checkerframework.checker.i18n.qual",
- "org.checkerframework.checker.i18nformatter.qual",
- "org.checkerframework.checker.index.qual",
- "org.checkerframework.checker.initialization.qual",
- "org.checkerframework.checker.interning.qual",
- "org.checkerframework.checker.lock.qual",
- "org.checkerframework.checker.mustcall.qual",
- "org.checkerframework.checker.nullness.qual",
- "org.checkerframework.checker.optional.qual",
- "org.checkerframework.checker.propkey.qual",
- "org.checkerframework.checker.regex.qual",
- "org.checkerframework.checker.signature.qual",
- "org.checkerframework.checker.signedness.qual",
- "org.checkerframework.checker.tainting.qual",
- "org.checkerframework.checker.units.qual",
- "org.checkerframework.common.aliasing.qual",
- "org.checkerframework.common.initializedfields.qual",
- "org.checkerframework.common.reflection.qual",
- "org.checkerframework.common.returnsreceiver.qual",
- "org.checkerframework.common.subtyping.qual",
- "org.checkerframework.common.util.report.qual",
- "org.checkerframework.common.value.qual",
- "org.checkerframework.dataflow.qual",
- "org.checkerframework.framework.qual"
- ]
- },
- "repositories": {
- "https://repo1.maven.org/maven2/": [
- "com.github.ben-manes.caffeine:caffeine",
- "com.github.stephenc.jcip:jcip-annotations",
- "com.google.auto.service:auto-service",
- "com.google.auto.service:auto-service-annotations",
- "com.google.auto.value:auto-value",
- "com.google.auto.value:auto-value-annotations",
- "com.google.auto:auto-common",
- "com.google.code.findbugs:jsr305",
- "com.google.code.gson:gson",
- "com.google.errorprone:error_prone_annotations",
- "com.google.errorprone:error_prone_type_annotations",
- "com.google.flogger:flogger",
- "com.google.flogger:flogger-system-backend",
- "com.google.flogger:google-extensions",
- "com.google.guava:failureaccess",
- "com.google.guava:guava",
- "com.google.guava:listenablefuture",
- "com.google.j2objc:j2objc-annotations",
- "com.ryanharter.auto.value:auto-value-gson-extension",
- "com.ryanharter.auto.value:auto-value-gson-factory",
- "com.ryanharter.auto.value:auto-value-gson-runtime",
- "com.squareup:javapoet",
- "commons-collections:commons-collections",
- "commons-lang:commons-lang",
- "io.sweers.autotransient:autotransient",
- "org.apache.tomcat:tomcat-annotations-api",
- "org.apache.velocity:velocity",
- "org.checkerframework:checker-compat-qual",
- "org.checkerframework:checker-qual"
- ]
- },
- "version": "2"
-}
diff --git a/stardoc/BUILD b/stardoc/BUILD
index b6ee9cd..8700982 100644
--- a/stardoc/BUILD
+++ b/stardoc/BUILD
@@ -1,5 +1,4 @@
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
-load("@rules_java//java:defs.bzl", "java_binary", "java_import")
load("//stardoc:stardoc.bzl", "stardoc")
licenses(["notice"])
@@ -50,20 +49,6 @@
deps = [":stardoc_lib"],
)
-java_binary(
- name = "stardoc",
- main_class = "com.google.devtools.build.skydoc.SkydocMain",
- runtime_deps = [
- ":prebuilt_stardoc_binary",
- ],
-)
-
-java_import(
- name = "prebuilt_stardoc_binary",
- jars = ["stardoc_binary.jar"],
- visibility = ["//visibility:public"],
-)
-
alias(
name = "renderer",
actual = "//src/main/java/com/google/devtools/build/skydoc/renderer",
@@ -76,7 +61,6 @@
"BUILD",
] + glob([
"*.bzl",
- "*.jar",
"templates/**",
]),
visibility = ["//:__pkg__"],
diff --git a/stardoc/private/stardoc.bzl b/stardoc/private/stardoc.bzl
index 4cb0949..0f614dd 100644
--- a/stardoc/private/stardoc.bzl
+++ b/stardoc/private/stardoc.bzl
@@ -63,52 +63,6 @@
(ctx.label.name)),
)
-def _stardoc_impl(ctx):
- """Implementation of the stardoc rule."""
- for semantic_flag in ctx.attr.semantic_flags:
- if not semantic_flag.startswith("--"):
- fail("semantic_flags entry '%s' must start with '--'" % semantic_flag)
- out_file = ctx.outputs.out
- stardoc_args = ctx.actions.args()
- stardoc_args.add("--input=" + str(ctx.file.input.owner))
- stardoc_args.add("--workspace_name=" + ctx.workspace_name)
- stardoc_args.add_all(
- ctx.attr.symbol_names,
- format_each = "--symbols=%s",
- omit_if_empty = True,
- )
- stardoc_args.add_all(ctx.attr.semantic_flags)
- stardoc = ctx.executable.stardoc
-
- if ctx.attr.format == "proto":
- stardoc_args.add("--output=" + out_file.path)
- ctx.actions.run(
- outputs = [out_file],
- executable = stardoc,
- arguments = [stardoc_args],
- mnemonic = "Stardoc",
- progress_message = ("Generating proto for Starlark doc for %s" %
- (ctx.label.name)),
- )
- elif ctx.attr.format == "markdown":
- proto_file = ctx.actions.declare_file(ctx.label.name + ".raw", sibling = out_file)
- stardoc_args.add("--output=" + proto_file.path)
- ctx.actions.run(
- outputs = [proto_file],
- executable = stardoc,
- arguments = [stardoc_args],
- mnemonic = "Stardoc",
- progress_message = ("Generating proto for Starlark doc for %s" %
- (ctx.label.name)),
- )
- _renderer_action_run(ctx, out_file = out_file, proto_file = proto_file)
-
- # Work around default outputs not getting captured by sh_binary:
- # https://github.com/bazelbuild/bazel/issues/15043.
- # See discussion in https://github.com/bazelbuild/stardoc/pull/139.
- outputs = [out_file]
- return [DefaultInfo(files = depset(outputs), runfiles = ctx.runfiles(files = outputs))]
-
_common_renderer_attrs = {
"out": attr.output(
doc = "The (markdown) file to which documentation will be output.",
@@ -155,14 +109,12 @@
mandatory = True,
),
"repository_rule_template": attr.label(
- doc = "The input file template for generating documentation of repository rules." +
- " This template is not used when rendering the output of the legacy extractor.",
+ doc = "The input file template for generating documentation of repository rules.",
allow_single_file = [".vm"],
mandatory = True,
),
"module_extension_template": attr.label(
- doc = "The input file template for generating documentation of module extensions." +
- " This template is not used when rendering the output of the legacy extractor.",
+ doc = "The input file template for generating documentation of module extensions.",
allow_single_file = [".vm"],
mandatory = True,
),
@@ -176,57 +128,6 @@
),
}
-# TODO(arostovtsev): replace with ... attrs = { ... } | _common_renderer_attrs
-# in rule definition below after we drop support for Bazel 5.
-_stardoc_attrs = {
- "input": attr.label(
- doc = "The starlark file to generate documentation for.",
- allow_single_file = [".bzl"],
- mandatory = True,
- ),
- "format": attr.string(
- doc = "The format of the output file. Valid values: 'markdown' or 'proto'.",
- values = ["markdown", "proto"],
- mandatory = True,
- ),
- "symbol_names": attr.string_list(
- doc = """
-A list of symbol names to generate documentation for. These should correspond to
-the names of rule definitions in the input file. If this list is empty, then
-documentation for all exported rule definitions will be generated.
-""",
- mandatory = True,
- ),
- "semantic_flags": attr.string_list(
- doc = """
-A list of canonical flags to affect Starlark semantics for the Starlark interpretter
-during documentation generation. This should only be used to maintain compatibility with
-non-default semantic flags required to use the given Starlark symbols.
-
-For example, if `//foo:bar.bzl` does not build except when a user would specify
-`--incompatible_foo_semantic=false`, then this attribute should contain
-"--incompatible_foo_semantic=false".
-""",
- mandatory = True,
- ),
- "stardoc": attr.label(
- doc = "The location of the stardoc tool.",
- allow_files = True,
- cfg = "exec",
- executable = True,
- mandatory = True,
- ),
-}
-_stardoc_attrs.update(_common_renderer_attrs.items())
-
-stardoc = rule(
- _stardoc_impl,
- doc = """
-Generates documentation for starlark skylark rule definitions in a target starlark file.
-""",
- attrs = _stardoc_attrs,
-)
-
def _stardoc_markdown_renderer_impl(ctx):
out_file = ctx.outputs.out
_renderer_action_run(ctx, out_file = out_file, proto_file = ctx.file.src)
diff --git a/stardoc/proto/stardoc_output.proto b/stardoc/proto/stardoc_output.proto
index 409017f..8b3ee96 100644
--- a/stardoc/proto/stardoc_output.proto
+++ b/stardoc/proto/stardoc_output.proto
@@ -12,8 +12,8 @@
// See the License for the specific language governing permissions and
// limitations under the License.
//
-// Vendored from src/main/java/com/google/devtools/build/skydoc/rendering/proto/stardoc_output.proto
-// in the Bazel source tree at commit bf5504a8c8f2d5e91acb18db864b2dae0d90ca7f
+// Vendored from src/main/protobuf/stardoc_output.proto
+// in the Bazel source tree at commit 18a674ba8f92f2eaa7e4f66650a0f764f88f95adn
//
// Protos for Stardoc data.
//
@@ -49,6 +49,8 @@
repeated ModuleExtensionInfo module_extension_info = 7;
repeated RepositoryRuleInfo repository_rule_info = 8;
+
+ repeated MacroInfo macro_info = 9;
}
// Representation of a Starlark rule attribute type. These generally
@@ -104,6 +106,26 @@
bool executable = 7;
}
+// Representation of a Starlark symbolic macro definition.
+// Note: symbolic macros (and thus, their documentation format) are an
+// experimental feature gated by the --experimental_enable_first_class_macros
+// flag.
+message MacroInfo {
+ // The name under which the macro is made accessible to a user of this module,
+ // including any structs it is nested in, for example "foo.foo_library".
+ string macro_name = 1;
+
+ // The documentation string of the macro.
+ string doc_string = 2;
+
+ // The attributes of the macro.
+ repeated AttributeInfo attribute = 3;
+
+ // The module where and the name under which the macro was originally
+ // declared.
+ OriginKey origin_key = 4;
+}
+
// Representation of a Starlark rule, repository rule, or module extension tag
// attribute definition, comprised of an attribute name, and a schema defined by
// a call to one of the 'attr' module methods enumerated at
diff --git a/stardoc/stardoc.bzl b/stardoc/stardoc.bzl
index b9cef93..d42a7a6 100644
--- a/stardoc/stardoc.bzl
+++ b/stardoc/stardoc.bzl
@@ -15,8 +15,7 @@
"""Starlark rule for stardoc: a documentation generator tool written in Java."""
load("@bazel_skylib//rules:copy_file.bzl", "copy_file")
-load("@rules_java//java:defs.bzl", "java_binary")
-load("//stardoc/private:stardoc.bzl", "stardoc_markdown_renderer", _stardoc = "stardoc")
+load("//stardoc/private:stardoc.bzl", "stardoc_markdown_renderer")
def stardoc(
*,
@@ -26,8 +25,6 @@
deps = [],
format = "markdown",
symbol_names = [],
- semantic_flags = [],
- stardoc = Label("//stardoc:prebuilt_stardoc_binary"),
renderer = Label("//stardoc:renderer"),
aspect_template = Label("//stardoc:templates/markdown_tables/aspect.vm"),
func_template = Label("//stardoc:templates/markdown_tables/func.vm"),
@@ -38,7 +35,6 @@
repository_rule_template = Label("//stardoc:templates/markdown_tables/repository_rule.vm"),
module_extension_template = Label("//stardoc:templates/markdown_tables/module_extension.vm"),
footer_template = None,
- use_starlark_doc_extract = True,
render_main_repo_name = True,
stamp = False,
**kwargs):
@@ -53,14 +49,6 @@
symbol_names: A list of symbol names to generate documentation for. These should correspond to the names of rule
definitions in the input file. If this list is empty, then documentation for all exported rule definitions will
be generated.
- semantic_flags: A list of canonical flags to affect Starlark semantics for the Starlark interpreter during
- documentation generation. This should only be used to maintain compatibility with non-default semantic flags
- required to use the given Starlark symbols.
-
- For example, if `//foo:bar.bzl` does not build except when a user would specify
- `--incompatible_foo_semantic=false`, then this attribute should contain
- "--incompatible_foo_semantic=false".
- stardoc: The location of the legacy Stardoc extractor. Ignored when using the native `starlark_doc_extract` rule.
renderer: The location of the renderer tool.
aspect_template: The input file template for generating documentation of aspects
header_template: The input file template for the header of the output documentation.
@@ -71,14 +59,10 @@
provider_template: The input file template for generating documentation of providers.
rule_template: The input file template for generating documentation of rules.
repository_rule_template: The input file template for generating documentation of repository rules.
- This template is used only when using the native `starlark_doc_extract` rule.
module_extension_template: The input file template for generating documentation of module extensions.
- This template is used only when using the native `starlark_doc_extract` rule.
footer_template: The input file template for generating the footer of the output documentation. Optional.
render_main_repo_name: Render labels in the main repository with a repo component (either
- the module name or workspace name). This parameter is used only when using the native
- `starlark_doc_extract` rule.
- use_starlark_doc_extract: Use the native `starlark_doc_extract` rule if available.
+ the module name or workspace name).
stamp: Whether to provide stamping information to templates.
**kwargs: Further arguments to pass to stardoc.
"""
@@ -93,79 +77,46 @@
if "testonly" in kwargs:
auxiliary_target_kwargs["testonly"] = kwargs["testonly"]
- if use_starlark_doc_extract and hasattr(native, "starlark_doc_extract"):
- # Use native.starlark_doc_extract as extractor
- if format == "proto" and Label(name + ".binaryproto") == Label(out):
- extractor_is_main_target = True
- extractor_name = name
- else:
- extractor_is_main_target = False
- extractor_name = name + ".extract"
-
- proto_name = extractor_name + ".binaryproto"
-
- native.starlark_doc_extract(
- name = extractor_name,
- src = input,
- deps = deps,
- render_main_repo_name = render_main_repo_name,
- symbol_names = symbol_names,
- **(kwargs if extractor_is_main_target else auxiliary_target_kwargs)
- )
-
- if format == "markdown":
- stardoc_markdown_renderer(
- name = name,
- src = proto_name,
- out = out,
- renderer = renderer,
- aspect_template = aspect_template,
- func_template = func_template,
- header_template = header_template,
- table_of_contents_template = table_of_contents_template,
- provider_template = provider_template,
- rule_template = rule_template,
- repository_rule_template = repository_rule_template,
- module_extension_template = module_extension_template,
- footer_template = footer_template,
- stamp = stamp,
- **kwargs
- )
- elif format == "proto" and not extractor_is_main_target:
- copy_file(
- name = name,
- src = proto_name,
- out = out,
- **kwargs
- )
-
+ if format == "proto" and Label(name + ".binaryproto") == Label(out):
+ extractor_is_main_target = True
+ extractor_name = name
else:
- # Use legacy extractor
- stardoc_with_runfiles_name = name + "_stardoc"
+ extractor_is_main_target = False
+ extractor_name = name + ".extract"
- java_binary(
- name = stardoc_with_runfiles_name,
- main_class = "com.google.devtools.build.skydoc.SkydocMain",
- runtime_deps = [stardoc],
- data = [input] + deps,
- **auxiliary_target_kwargs
- )
+ proto_name = extractor_name + ".binaryproto"
- _stardoc(
+ native.starlark_doc_extract(
+ name = extractor_name,
+ src = input,
+ deps = deps,
+ render_main_repo_name = render_main_repo_name,
+ symbol_names = symbol_names,
+ **(kwargs if extractor_is_main_target else auxiliary_target_kwargs)
+ )
+
+ if format == "markdown":
+ stardoc_markdown_renderer(
name = name,
- input = input,
+ src = proto_name,
out = out,
- format = format,
- symbol_names = symbol_names,
- semantic_flags = semantic_flags,
- stardoc = stardoc_with_runfiles_name,
renderer = renderer,
aspect_template = aspect_template,
func_template = func_template,
header_template = header_template,
+ table_of_contents_template = table_of_contents_template,
provider_template = provider_template,
rule_template = rule_template,
repository_rule_template = repository_rule_template,
module_extension_template = module_extension_template,
+ footer_template = footer_template,
+ stamp = stamp,
+ **kwargs
+ )
+ elif format == "proto" and not extractor_is_main_target:
+ copy_file(
+ name = name,
+ src = proto_name,
+ out = out,
**kwargs
)
diff --git a/stardoc/stardoc_binary.jar b/stardoc/stardoc_binary.jar
deleted file mode 100755
index 031e580..0000000
--- a/stardoc/stardoc_binary.jar
+++ /dev/null
Binary files differ
diff --git a/test/BUILD b/test/BUILD
index 81aa24c..bc3ebcb 100644
--- a/test/BUILD
+++ b/test/BUILD
@@ -9,7 +9,6 @@
self_gen_test(
name = "stardoc_self_gen_test",
golden_file = "//stardoc:stardoc_doc.md",
- require_starlark_doc_extract = True,
stardoc_doc = "//:stardoc_rule_doc",
)
@@ -30,7 +29,6 @@
name = "angle_bracket_test",
golden_file = "testdata/angle_bracket_test/golden.md",
input_file = "testdata/angle_bracket_test/input.bzl",
- legacy_golden_file = "testdata/angle_bracket_test/legacy_golden.md",
)
stardoc_test(
@@ -38,7 +36,6 @@
format = "proto",
golden_file = "testdata/proto_format_test/golden.binaryproto",
input_file = "testdata/proto_format_test/input.bzl",
- legacy_golden_file = "testdata/proto_format_test/legacy_golden.binaryproto",
)
stardoc_test(
@@ -58,14 +55,12 @@
name = "repo_rules_test",
golden_file = "testdata/repo_rules_test/golden.md",
input_file = "testdata/repo_rules_test/input.bzl",
- legacy_golden_file = "testdata/repo_rules_test/legacy_golden.md",
)
stardoc_test(
name = "module_extension_test",
golden_file = "testdata/module_extension_test/golden.md",
input_file = "testdata/module_extension_test/input.bzl",
- test_legacy_extractor = False,
)
stardoc_test(
@@ -84,9 +79,6 @@
name = "android_basic_test",
golden_file = "testdata/android_basic_test/golden.md",
input_file = "testdata/android_basic_test/input.bzl",
- semantic_flags = [
- "--experimental_google_legacy_api",
- ],
symbol_names = ["android_related_rule"],
)
@@ -135,14 +127,12 @@
name = "misc_apis_test",
golden_file = "testdata/misc_apis_test/golden.md",
input_file = "testdata/misc_apis_test/input.bzl",
- legacy_golden_file = "testdata/misc_apis_test/legacy_golden.md",
)
stardoc_test(
name = "attribute_types_test",
golden_file = "testdata/attribute_types_test/golden.md",
input_file = "testdata/attribute_types_test/input.bzl",
- legacy_golden_file = "testdata/attribute_types_test/legacy_golden.md",
symbol_names = ["my_rule"],
)
@@ -163,7 +153,6 @@
name = "provider_basic_test",
golden_file = "testdata/provider_basic_test/golden.md",
input_file = "testdata/provider_basic_test/input.bzl",
- legacy_golden_file = "testdata/provider_basic_test/legacy_golden.md",
)
stardoc_test(
@@ -176,7 +165,6 @@
name = "function_wrap_multiple_lines_test",
golden_file = "testdata/function_wrap_multiple_lines_test/golden.md",
input_file = "testdata/function_wrap_multiple_lines_test/input.bzl",
- legacy_golden_file = "testdata/function_wrap_multiple_lines_test/legacy_golden.md",
)
stardoc_test(
@@ -239,7 +227,6 @@
name = "aspect_test",
golden_file = "testdata/aspect_test/golden.md",
input_file = "testdata/aspect_test/input.bzl",
- legacy_golden_file = "testdata/aspect_test/legacy_golden.md",
)
stardoc_test(
@@ -262,7 +249,6 @@
name = "attribute_defaults_test",
golden_file = "testdata/attribute_defaults_test/golden.md",
input_file = "testdata/attribute_defaults_test/input.bzl",
- legacy_golden_file = "testdata/attribute_defaults_test/legacy_golden.md",
)
stardoc_test(
@@ -276,7 +262,6 @@
footer_template = "testdata/footer_test/footer_template.vm",
golden_file = "testdata/footer_test/golden.md",
input_file = "testdata/footer_test/input.bzl",
- test_legacy_extractor = False,
)
bzl_library(
@@ -296,7 +281,6 @@
golden_file = "testdata/table_of_contents_test/golden.md",
input_file = "testdata/table_of_contents_test/input.bzl",
table_of_contents_template = "//stardoc:templates/markdown_tables/table_of_contents.vm",
- test_legacy_extractor = False,
deps = [":table_of_contents_test_deps"],
)
@@ -306,7 +290,6 @@
header_template = "testdata/stamping_test/stamping_header.vm",
input_file = "testdata/stamping_test/input.bzl",
stamp = True,
- test_legacy_extractor = False,
)
stardoc_test(
@@ -315,7 +298,6 @@
header_template = "testdata/stamping_test/stamping_header_stamping_off.vm",
input_file = "testdata/stamping_test/input.bzl",
stamp = False,
- test_legacy_extractor = False,
)
sh_test(
diff --git a/test/stardoc_test.bzl b/test/stardoc_test.bzl
index d782643..d7c20d5 100644
--- a/test/stardoc_test.bzl
+++ b/test/stardoc_test.bzl
@@ -21,8 +21,6 @@
name,
input_file,
golden_file,
- legacy_golden_file = None,
- test_legacy_extractor = True,
deps = [],
test = "default",
**kwargs):
@@ -30,18 +28,12 @@
Each invocation creates multiple targets:
- 1. A sh_test target which verifies that stardoc-built-from-source, when run on an input file,
- creates output matching the contents of a golden file, named "{name}_e2e_legacy_test".
- 2. A `stardoc` target which will generate a new golden file given an input file with the
- legacy extractor built from Bazel source. This target should be used to regenerate the
- legacy golden file when updating stardoc, named "regenerate_{name}_legacy_golden".
- 3 & 4. Targets identical to (1) and (2) except they use the prebuilt-stardoc jar, and
- are named "{name}_e2e_jar_legacy_test" and "regenerate_with_jar_{name}_legacy_golden".
- 5 & 6. Only if the host Bazel supports the `native.starlark_doc_extract` rule: Targets
- identical to (1) and (2) except they use starlark_doc_extract, and are named "{name}_e2e_test"
- and "regenerate_{name}_golden". The latter target should be used to regenerate the golden
- file when updating Stardoc.
- 7. A bzl_library target for convenient wrapping of input bzl files, named "{name}_lib".
+ 1. A `stardoc` target which will generate a new golden file given an input
+ file. This target should be used to regenerate the golden file when
+ updating Stardoc, named "regenerate_{name}_golden".
+ 2. An `sh_test` target which verifies that the output of the `stardoc`
+ target above matches a golden file.
+ 3. A bzl_library target for convenient wrapping of input bzl files, named "{name}_lib".
Args:
name: A unique name to qualify the created targets.
@@ -49,60 +41,25 @@
in this test.
golden_file: The label string of the golden file containing the documentation when stardoc
is run on the input file.
- legacy_golden_file: The label string of the golden file when using the legacy documentation
- extractor. If `legacy_golden_file` is not set, `golden_file` will be used for both extractors.
- test_legacy_extractor: Whether to create legacy extractor test targets.
deps: A list of label strings of starlark file dependencies of the input_file.
test: The type of test (default or html_tables).
**kwargs: A dictionary of input template names mapped to template file path for which documentation is generated.
"""
-
- if legacy_golden_file == None:
- legacy_golden_file = golden_file
-
bzl_library(
name = "%s_lib" % name,
srcs = [input_file],
deps = deps,
)
- if test_legacy_extractor:
- _create_test_targets(
- test_name = "%s_e2e_legacy_test" % name,
- genrule_name = "regenerate_%s_legacy_golden" % name,
- lib_name = "%s_lib" % name,
- input_file = input_file,
- golden_file = legacy_golden_file,
- stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc:skydoc_deploy.jar",
- test = test,
- use_starlark_doc_extract = False,
- **kwargs
- )
-
- _create_test_targets(
- test_name = "%s_e2e_jar_legacy_test" % name,
- genrule_name = "regenerate_with_jar_%s_legacy_golden" % name,
- lib_name = "%s_lib" % name,
- input_file = input_file,
- golden_file = legacy_golden_file,
- stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc:skydoc_deploy.jar",
- test = test,
- use_starlark_doc_extract = False,
- **kwargs
- )
-
- if hasattr(native, "starlark_doc_extract"):
- _create_test_targets(
- test_name = "%s_e2e_test" % name,
- genrule_name = "regenerate_%s_golden" % name,
- lib_name = "%s_lib" % name,
- input_file = input_file,
- golden_file = golden_file,
- stardoc_bin = None,
- test = test,
- use_starlark_doc_extract = True,
- **kwargs
- )
+ _create_test_targets(
+ test_name = "%s_e2e_test" % name,
+ genrule_name = "regenerate_%s_golden" % name,
+ lib_name = "%s_lib" % name,
+ input_file = input_file,
+ golden_file = golden_file,
+ test = test,
+ **kwargs
+ )
def _create_test_targets(
test_name,
@@ -110,7 +67,6 @@
lib_name,
input_file,
golden_file,
- stardoc_bin,
test,
**kwargs):
actual_generated_doc = "%s.out" % genrule_name
@@ -134,7 +90,6 @@
out = actual_generated_doc,
input = input_file,
deps = [lib_name],
- stardoc = stardoc_bin,
**kwargs
)
elif test == "html_tables":
@@ -143,7 +98,6 @@
out = actual_generated_doc,
input = input_file,
deps = [lib_name],
- stardoc = stardoc_bin,
**kwargs
)
else:
@@ -153,7 +107,6 @@
name,
stardoc_doc,
golden_file,
- require_starlark_doc_extract,
**kwargs):
"""
A wrapper around `diff_test_runner.sh` for testing Stardoc's own generated documentation.
@@ -162,13 +115,8 @@
name: A unique name for the test target.
stardoc_doc: The Stardoc output being tested.
golden_file: Expected Stardoc output.
- require_starlark_doc_extract: If true, and the native `starlark_doc_extract` rule is not available,
- then no test target will not be created.
**kwargs: Additional arguments for the test.
"""
- if require_starlark_doc_extract and not hasattr(native, "starlark_doc_extract"):
- return
-
native.sh_test(
name = name,
srcs = ["diff_test_runner.sh"],
diff --git a/test/testdata/angle_bracket_test/legacy_golden.md b/test/testdata/angle_bracket_test/legacy_golden.md
deleted file mode 100644
index 42f8fc6..0000000
--- a/test/testdata/angle_bracket_test/legacy_golden.md
+++ /dev/null
@@ -1,124 +0,0 @@
-<!-- Generated with Stardoc: http://skydoc.bazel.build -->
-
-Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issues/186)
-
-See https://github.com/bazelbuild/skydoc/issues/186,
-https://github.com/bazelbuild/stardoc/issues/132,
-and https://github.com/bazelbuild/stardoc/issues/137.
-
-<b>HTML formatting</b> can be used in docstrings, just as in regular Markdown.
-Literal angle brackets can be obtained by escaping them with a backslash, where
-the backslash itself must be escaped for use in a Starlark docstring
-(`\\<` becomes \<), or by using HTML entities (`<` becomes <).
-Angle brackets are also preserved in inline code blocks (`#include <vector>`).
-
-<a id="my_anglebrac"></a>
-
-## my_anglebrac
-
-<pre>
-my_anglebrac(<a href="#my_anglebrac-name">name</a>, <a href="#my_anglebrac-also_useless">also_useless</a>, <a href="#my_anglebrac-useless">useless</a>)
-</pre>
-
-Rule with \<brackets>
-
-**ATTRIBUTES**
-
-
-| Name | Description | Type | Mandatory | Default |
-| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="my_anglebrac-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="my_anglebrac-also_useless"></a>also_useless | Args with some formatted tags: `<tag>` and <pre><code class="language-xml"><tag2>x</tag2></code></pre> | String | optional | `"1<<5"` |
-| <a id="my_anglebrac-useless"></a>useless | Args with some tags: \<tag1>, \<tag2> | String | optional | `"Find \<brackets>"` |
-
-
-<a id="bracketuse"></a>
-
-## bracketuse
-
-<pre>
-bracketuse(<a href="#bracketuse-foo">foo</a>, <a href="#bracketuse-bar">bar</a>, <a href="#bracketuse-baz">baz</a>)
-</pre>
-
-Information with \<brackets>
-
-**FIELDS**
-
-
-| Name | Description |
-| :------------- | :------------- |
-| <a id="bracketuse-foo"></a>foo | A string representing \<foo> |
-| <a id="bracketuse-bar"></a>bar | A string representing bar |
-| <a id="bracketuse-baz"></a>baz | A string representing baz |
-
-
-<a id="bracket_function"></a>
-
-## bracket_function
-
-<pre>
-bracket_function(<a href="#bracket_function-param">param</a>, <a href="#bracket_function-md_string">md_string</a>)
-</pre>
-
-Dummy docstring with \<brackets>.
-
-This rule runs checks on `<angle brackets>`.
-
-Sometimes, we have such things on their own, but they may
-also appear in code blocks, like
-
-```starlark
-foo = "<thing>"
-```
-
-
-**PARAMETERS**
-
-
-| Name | Description | Default Value |
-| :------------- | :------------- | :------------- |
-| <a id="bracket_function-param"></a>param | an arg with **formatted** docstring, `<default>` by default. | `"<default>"` |
-| <a id="bracket_function-md_string"></a>md_string | A markdown string. | ``"foo `1<<10` bar"`` |
-
-**RETURNS**
-
-some \<angled> brackets
-
-**DEPRECATED**
-
-deprecated for \<reasons> as well as `<reasons>`.
-
-
-<a id="bracket_aspect"></a>
-
-## bracket_aspect
-
-<pre>
-bracket_aspect(<a href="#bracket_aspect-name">name</a>, <a href="#bracket_aspect-brackets">brackets</a>)
-</pre>
-
-Aspect.
-
-Sometimes, we want a code block like
-```starlark
-foo = "<brackets>"
-```
-which includes angle brackets.
-
-**ASPECT ATTRIBUTES**
-
-
-| Name | Type |
-| :------------- | :------------- |
-| deps| String |
-
-
-**ATTRIBUTES**
-
-
-| Name | Description | Type | Mandatory | Default |
-| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="bracket_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="bracket_aspect-brackets"></a>brackets | Attribute with \<brackets> | String | optional | `"<default>"` |
-
-
diff --git a/test/testdata/aspect_test/legacy_golden.md b/test/testdata/aspect_test/legacy_golden.md
deleted file mode 100644
index 283689a..0000000
--- a/test/testdata/aspect_test/legacy_golden.md
+++ /dev/null
@@ -1,80 +0,0 @@
-<!-- Generated with Stardoc: http://skydoc.bazel.build -->
-
-The input file for the aspect test
-
-<a id="my_aspect_impl"></a>
-
-## my_aspect_impl
-
-<pre>
-my_aspect_impl(<a href="#my_aspect_impl-ctx">ctx</a>)
-</pre>
-
-
-
-**PARAMETERS**
-
-
-| Name | Description | Default Value |
-| :------------- | :------------- | :------------- |
-| <a id="my_aspect_impl-ctx"></a>ctx | <p align="center"> - </p> | none |
-
-
-<a id="my_aspect"></a>
-
-## my_aspect
-
-<pre>
-my_aspect(<a href="#my_aspect-name">name</a>, <a href="#my_aspect-first">first</a>, <a href="#my_aspect-second">second</a>)
-</pre>
-
-This is my aspect.
-
-It does stuff.
-
-**ASPECT ATTRIBUTES**
-
-
-| Name | Type |
-| :------------- | :------------- |
-| deps| String |
-| attr_aspect| String |
-
-
-**ATTRIBUTES**
-
-
-| Name | Description | Type | Mandatory | Default |
-| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="my_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="my_aspect-first"></a>first | - | Boolean | required | |
-| <a id="my_aspect-second"></a>second | - | String | required | |
-
-
-<a id="other_aspect"></a>
-
-## other_aspect
-
-<pre>
-other_aspect(<a href="#other_aspect-name">name</a>, <a href="#other_aspect-third">third</a>)
-</pre>
-
-This is another aspect.
-
-**ASPECT ATTRIBUTES**
-
-
-| Name | Type |
-| :------------- | :------------- |
-| *| String |
-
-
-**ATTRIBUTES**
-
-
-| Name | Description | Type | Mandatory | Default |
-| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="other_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="other_aspect-third"></a>third | - | Integer | required | |
-
-
diff --git a/test/testdata/attribute_defaults_test/legacy_golden.md b/test/testdata/attribute_defaults_test/legacy_golden.md
deleted file mode 100644
index 4eaf4b9..0000000
--- a/test/testdata/attribute_defaults_test/legacy_golden.md
+++ /dev/null
@@ -1,74 +0,0 @@
-<!-- Generated with Stardoc: http://skydoc.bazel.build -->
-
-A golden test to verify attribute default values.
-
-<a id="my_rule"></a>
-
-## my_rule
-
-<pre>
-my_rule(<a href="#my_rule-name">name</a>, <a href="#my_rule-a">a</a>, <a href="#my_rule-b">b</a>, <a href="#my_rule-c">c</a>, <a href="#my_rule-d">d</a>, <a href="#my_rule-e">e</a>, <a href="#my_rule-f">f</a>, <a href="#my_rule-g">g</a>, <a href="#my_rule-h">h</a>, <a href="#my_rule-i">i</a>, <a href="#my_rule-j">j</a>, <a href="#my_rule-k">k</a>, <a href="#my_rule-l">l</a>, <a href="#my_rule-m">m</a>, <a href="#my_rule-n">n</a>, <a href="#my_rule-o">o</a>, <a href="#my_rule-p">p</a>, <a href="#my_rule-q">q</a>, <a href="#my_rule-r">r</a>, <a href="#my_rule-s">s</a>, <a href="#my_rule-t">t</a>, <a href="#my_rule-u">u</a>, <a href="#my_rule-v">v</a>, <a href="#my_rule-w">w</a>)
-</pre>
-
-This is my rule. It does stuff.
-
-**ATTRIBUTES**
-
-
-| Name | Description | Type | Mandatory | Default |
-| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="my_rule-a"></a>a | Some bool | Boolean | optional | `False` |
-| <a id="my_rule-b"></a>b | Some int | Integer | optional | `2` |
-| <a id="my_rule-c"></a>c | Some int_list | List of integers | optional | `[0, 1]` |
-| <a id="my_rule-d"></a>d | Some label | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `//foo:bar` |
-| <a id="my_rule-e"></a>e | Some label_keyed_string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | `{"//foo:bar": "hello", "//bar:baz": "goodbye"}` |
-| <a id="my_rule-f"></a>f | Some label_list | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `["//foo:bar", "//bar:baz"]` |
-| <a id="my_rule-g"></a>g | Some string | String | optional | `""` |
-| <a id="my_rule-h"></a>h | Some string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{"animal": "bunny", "color": "orange"}` |
-| <a id="my_rule-i"></a>i | Some string_list | List of strings | optional | `["cat", "dog"]` |
-| <a id="my_rule-j"></a>j | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | optional | `{"animal": ["cat", "bunny"], "color": ["blue", "orange"]}` |
-| <a id="my_rule-k"></a>k | Some bool | Boolean | required | |
-| <a id="my_rule-l"></a>l | Some int | Integer | required | |
-| <a id="my_rule-m"></a>m | Some int_list | List of integers | required | |
-| <a id="my_rule-n"></a>n | Some label | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
-| <a id="my_rule-o"></a>o | Some label_keyed_string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | required | |
-| <a id="my_rule-p"></a>p | Some label_list | <a href="https://bazel.build/concepts/labels">List of labels</a> | required | |
-| <a id="my_rule-q"></a>q | Some string | String | required | |
-| <a id="my_rule-r"></a>r | Some string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | |
-| <a id="my_rule-s"></a>s | Some string_list | List of strings | required | |
-| <a id="my_rule-t"></a>t | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | required | |
-| <a id="my_rule-u"></a>u | - | String | optional | `""` |
-| <a id="my_rule-v"></a>v | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` |
-| <a id="my_rule-w"></a>w | - | Integer | optional | `0` |
-
-
-<a id="my_aspect"></a>
-
-## my_aspect
-
-<pre>
-my_aspect(<a href="#my_aspect-name">name</a>, <a href="#my_aspect-y">y</a>, <a href="#my_aspect-z">z</a>)
-</pre>
-
-This is my aspect. It does stuff.
-
-**ASPECT ATTRIBUTES**
-
-
-| Name | Type |
-| :------------- | :------------- |
-| deps| String |
-| attr_aspect| String |
-
-
-**ATTRIBUTES**
-
-
-| Name | Description | Type | Mandatory | Default |
-| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="my_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="my_aspect-y"></a>y | some string | String | optional | `"why"` |
-| <a id="my_aspect-z"></a>z | - | String | required | |
-
-
diff --git a/test/testdata/attribute_types_test/legacy_golden.md b/test/testdata/attribute_types_test/legacy_golden.md
deleted file mode 100644
index aa2ae91..0000000
--- a/test/testdata/attribute_types_test/legacy_golden.md
+++ /dev/null
@@ -1,36 +0,0 @@
-<!-- Generated with Stardoc: http://skydoc.bazel.build -->
-
-
-
-<a id="my_rule"></a>
-
-## my_rule
-
-<pre>
-my_rule(<a href="#my_rule-name">name</a>, <a href="#my_rule-a">a</a>, <a href="#my_rule-b">b</a>, <a href="#my_rule-c">c</a>, <a href="#my_rule-d">d</a>, <a href="#my_rule-e">e</a>, <a href="#my_rule-f">f</a>, <a href="#my_rule-g">g</a>, <a href="#my_rule-h">h</a>, <a href="#my_rule-i">i</a>, <a href="#my_rule-j">j</a>, <a href="#my_rule-k">k</a>, <a href="#my_rule-l">l</a>)
-</pre>
-
-This is my rule.
-
-It does stuff.
-
-**ATTRIBUTES**
-
-
-| Name | Description | Type | Mandatory | Default |
-| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="my_rule-a"></a>a | Some bool | Boolean | required | |
-| <a id="my_rule-b"></a>b | Some int | Integer | required | |
-| <a id="my_rule-c"></a>c | Some int_list | List of integers | required | |
-| <a id="my_rule-d"></a>d | Some label | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
-| <a id="my_rule-e"></a>e | Some label_keyed_string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | required | |
-| <a id="my_rule-f"></a>f | Some label_list | <a href="https://bazel.build/concepts/labels">List of labels</a> | required | |
-| <a id="my_rule-g"></a>g | Some output | <a href="https://bazel.build/concepts/labels">Label</a> | optional | |
-| <a id="my_rule-h"></a>h | Some output_list | List of labels | optional | |
-| <a id="my_rule-i"></a>i | Some string | String | required | |
-| <a id="my_rule-j"></a>j | Some string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | |
-| <a id="my_rule-k"></a>k | Some string_list | List of strings | required | |
-| <a id="my_rule-l"></a>l | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | optional | `{}` |
-
-
diff --git a/test/testdata/function_wrap_multiple_lines_test/legacy_golden.md b/test/testdata/function_wrap_multiple_lines_test/legacy_golden.md
deleted file mode 100644
index aba7921..0000000
--- a/test/testdata/function_wrap_multiple_lines_test/legacy_golden.md
+++ /dev/null
@@ -1,56 +0,0 @@
-<!-- Generated with Stardoc: http://skydoc.bazel.build -->
-
-Rules for ANTLR 3.
-
-<a id="antlr"></a>
-
-## antlr
-
-<pre>
-antlr(<a href="#antlr-name">name</a>, <a href="#antlr-deps">deps</a>, <a href="#antlr-srcs">srcs</a>, <a href="#antlr-Xconversiontimeout">Xconversiontimeout</a>, <a href="#antlr-Xdbgconversion">Xdbgconversion</a>, <a href="#antlr-Xdbgst">Xdbgst</a>, <a href="#antlr-Xdfa">Xdfa</a>, <a href="#antlr-Xdfaverbose">Xdfaverbose</a>, <a href="#antlr-Xgrtree">Xgrtree</a>, <a href="#antlr-Xm">Xm</a>,
- <a href="#antlr-Xmaxdfaedges">Xmaxdfaedges</a>, <a href="#antlr-Xmaxinlinedfastates">Xmaxinlinedfastates</a>, <a href="#antlr-Xminswitchalts">Xminswitchalts</a>, <a href="#antlr-Xmultithreaded">Xmultithreaded</a>, <a href="#antlr-Xnfastates">Xnfastates</a>, <a href="#antlr-Xnocollapse">Xnocollapse</a>,
- <a href="#antlr-Xnomergestopstates">Xnomergestopstates</a>, <a href="#antlr-Xnoprune">Xnoprune</a>, <a href="#antlr-XsaveLexer">XsaveLexer</a>, <a href="#antlr-Xwatchconversion">Xwatchconversion</a>, <a href="#antlr-debug">debug</a>, <a href="#antlr-depend">depend</a>, <a href="#antlr-dfa">dfa</a>, <a href="#antlr-dump">dump</a>, <a href="#antlr-imports">imports</a>,
- <a href="#antlr-language">language</a>, <a href="#antlr-message_format">message_format</a>, <a href="#antlr-nfa">nfa</a>, <a href="#antlr-package">package</a>, <a href="#antlr-profile">profile</a>, <a href="#antlr-report">report</a>, <a href="#antlr-trace">trace</a>)
-</pre>
-
-Runs [ANTLR 3](https://www.antlr3.org//) on a set of grammars.
-
-**ATTRIBUTES**
-
-
-| Name | Description | Type | Mandatory | Default |
-| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="antlr-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="antlr-deps"></a>deps | 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. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[Label("@@antlr3_runtimes//:tool")]` |
-| <a id="antlr-srcs"></a>srcs | The grammar files to process. | <a href="https://bazel.build/concepts/labels">List of labels</a> | required | |
-| <a id="antlr-Xconversiontimeout"></a>Xconversiontimeout | Set NFA conversion timeout for each decision. | Integer | optional | `0` |
-| <a id="antlr-Xdbgconversion"></a>Xdbgconversion | Dump lots of info during NFA conversion. | Boolean | optional | `False` |
-| <a id="antlr-Xdbgst"></a>Xdbgst | Put tags at start/stop of all templates in output. | Boolean | optional | `False` |
-| <a id="antlr-Xdfa"></a>Xdfa | Print DFA as text. | Boolean | optional | `False` |
-| <a id="antlr-Xdfaverbose"></a>Xdfaverbose | Generate DFA states in DOT with NFA configs. | Boolean | optional | `False` |
-| <a id="antlr-Xgrtree"></a>Xgrtree | Print the grammar AST. | Boolean | optional | `False` |
-| <a id="antlr-Xm"></a>Xm | Max number of rule invocations during conversion. | Integer | optional | `0` |
-| <a id="antlr-Xmaxdfaedges"></a>Xmaxdfaedges | Max "comfortable" number of edges for single DFA state. | Integer | optional | `0` |
-| <a id="antlr-Xmaxinlinedfastates"></a>Xmaxinlinedfastates | Max DFA states before table used rather than inlining. | Integer | optional | `0` |
-| <a id="antlr-Xminswitchalts"></a>Xminswitchalts | Don't generate switch() statements for dfas smaller than given number. | Integer | optional | `0` |
-| <a id="antlr-Xmultithreaded"></a>Xmultithreaded | Run the analysis in 2 threads. | Boolean | optional | `False` |
-| <a id="antlr-Xnfastates"></a>Xnfastates | For nondeterminisms, list NFA states for each path. | Boolean | optional | `False` |
-| <a id="antlr-Xnocollapse"></a>Xnocollapse | Collapse incident edges into DFA states. | Boolean | optional | `False` |
-| <a id="antlr-Xnomergestopstates"></a>Xnomergestopstates | Max DFA states before table used rather than inlining. | Boolean | optional | `False` |
-| <a id="antlr-Xnoprune"></a>Xnoprune | Do not test EBNF block exit branches. | Boolean | optional | `False` |
-| <a id="antlr-XsaveLexer"></a>XsaveLexer | For nondeterminisms, list NFA states for each path. | Boolean | optional | `False` |
-| <a id="antlr-Xwatchconversion"></a>Xwatchconversion | Don't delete temporary lexers generated from combined grammars. | Boolean | optional | `False` |
-| <a id="antlr-debug"></a>debug | Generate a parser that emits debugging events. | Boolean | optional | `False` |
-| <a id="antlr-depend"></a>depend | Generate file dependencies; don't actually run antlr. | Boolean | optional | `False` |
-| <a id="antlr-dfa"></a>dfa | Generate a DFA for each decision point. | Boolean | optional | `False` |
-| <a id="antlr-dump"></a>dump | Print out the grammar without actions. | Boolean | optional | `False` |
-| <a id="antlr-imports"></a>imports | The grammar and .tokens files to import. Must be all in the same directory. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
-| <a id="antlr-language"></a>language | The code generation target language. Either C, Cpp, CSharp2, CSharp3, JavaScript, Java, ObjC, Python, Python3 or Ruby (case-sensitive). | String | optional | `""` |
-| <a id="antlr-message_format"></a>message_format | Specify output style for messages. | String | optional | `""` |
-| <a id="antlr-nfa"></a>nfa | Generate an NFA for each rule. | Boolean | optional | `False` |
-| <a id="antlr-package"></a>package | The package/namespace for the generated code. | String | optional | `""` |
-| <a id="antlr-profile"></a>profile | Generate a parser that computes profiling information. | Boolean | optional | `False` |
-| <a id="antlr-report"></a>report | Print out a report about the grammar(s) processed. | Boolean | optional | `False` |
-| <a id="antlr-trace"></a>trace | Generate a parser with trace output. If the default output is not enough, you can override the traceIn and traceOut methods. | Boolean | optional | `False` |
-
-
diff --git a/test/testdata/misc_apis_test/legacy_golden.md b/test/testdata/misc_apis_test/legacy_golden.md
deleted file mode 100644
index 1a6b867..0000000
--- a/test/testdata/misc_apis_test/legacy_golden.md
+++ /dev/null
@@ -1,76 +0,0 @@
-<!-- Generated with Stardoc: http://skydoc.bazel.build -->
-
-
-
-<a id="my_rule"></a>
-
-## my_rule
-
-<pre>
-my_rule(<a href="#my_rule-name">name</a>, <a href="#my_rule-deps">deps</a>, <a href="#my_rule-src">src</a>, <a href="#my_rule-out">out</a>, <a href="#my_rule-extra_arguments">extra_arguments</a>, <a href="#my_rule-tool">tool</a>)
-</pre>
-
-This rule exercises some of the build API.
-
-**ATTRIBUTES**
-
-
-| Name | Description | Type | Mandatory | Default |
-| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="my_rule-deps"></a>deps | A list of dependencies. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
-| <a id="my_rule-src"></a>src | The source file. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` |
-| <a id="my_rule-out"></a>out | The output file. | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
-| <a id="my_rule-extra_arguments"></a>extra_arguments | - | List of strings | optional | `[]` |
-| <a id="my_rule-tool"></a>tool | The location of the tool to use. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `//foo/bar/baz:target` |
-
-
-<a id="MyInfo"></a>
-
-## MyInfo
-
-<pre>
-MyInfo(<a href="#MyInfo-foo">foo</a>, <a href="#MyInfo-bar">bar</a>)
-</pre>
-
-
-
-**FIELDS**
-
-
-| Name | Description |
-| :------------- | :------------- |
-| <a id="MyInfo-foo"></a>foo | Something foo-related. |
-| <a id="MyInfo-bar"></a>bar | Something bar-related. |
-
-
-<a id="exercise_the_api"></a>
-
-## exercise_the_api
-
-<pre>
-exercise_the_api()
-</pre>
-
-
-
-
-
-<a id="my_rule_impl"></a>
-
-## my_rule_impl
-
-<pre>
-my_rule_impl(<a href="#my_rule_impl-ctx">ctx</a>)
-</pre>
-
-
-
-**PARAMETERS**
-
-
-| Name | Description | Default Value |
-| :------------- | :------------- | :------------- |
-| <a id="my_rule_impl-ctx"></a>ctx | <p align="center"> - </p> | none |
-
-
diff --git a/test/testdata/proto_format_test/legacy_golden.binaryproto b/test/testdata/proto_format_test/legacy_golden.binaryproto
deleted file mode 100644
index d158834..0000000
--- a/test/testdata/proto_format_test/legacy_golden.binaryproto
+++ /dev/null
@@ -1,17 +0,0 @@
-
-
-
-my_exampleSmall example of rule.*
-name A unique name for this target. 7
-useless This argument will be ignored.2
-"ignoreme"
-example$Stores information about an example.
-fooA string representing foo
-barA string representing bar
-bazA string representing bazÆ
-check_function%
-foo A unique name for this rule. Runs some checks on the given function parameter.
-
-This rule runs checks on a given function parameter.
-Use `bazel build` to run the check.
-* Input file for proto format test
\ No newline at end of file
diff --git a/test/testdata/provider_basic_test/legacy_golden.md b/test/testdata/provider_basic_test/legacy_golden.md
deleted file mode 100644
index 38dd0f6..0000000
--- a/test/testdata/provider_basic_test/legacy_golden.md
+++ /dev/null
@@ -1,58 +0,0 @@
-<!-- Generated with Stardoc: http://skydoc.bazel.build -->
-
-
-
-<a id="MyFooInfo"></a>
-
-## MyFooInfo
-
-<pre>
-MyFooInfo(<a href="#MyFooInfo-bar">bar</a>, <a href="#MyFooInfo-baz">baz</a>)
-</pre>
-
-Stores information about a foo.
-
-**FIELDS**
-
-
-| Name | Description |
-| :------------- | :------------- |
-| <a id="MyFooInfo-bar"></a>bar | (Undocumented) |
-| <a id="MyFooInfo-baz"></a>baz | (Undocumented) |
-
-
-<a id="MyPoorlyDocumentedInfo"></a>
-
-## MyPoorlyDocumentedInfo
-
-<pre>
-MyPoorlyDocumentedInfo()
-</pre>
-
-
-
-**FIELDS**
-
-
-
-<a id="MyVeryDocumentedInfo"></a>
-
-## MyVeryDocumentedInfo
-
-<pre>
-MyVeryDocumentedInfo(<a href="#MyVeryDocumentedInfo-favorite_food">favorite_food</a>, <a href="#MyVeryDocumentedInfo-favorite_color">favorite_color</a>)
-</pre>
-
-A provider with some really neat documentation.
-
-Look on my works, ye mighty, and despair!
-
-**FIELDS**
-
-
-| Name | Description |
-| :------------- | :------------- |
-| <a id="MyVeryDocumentedInfo-favorite_food"></a>favorite_food | A string representing my favorite food<br><br> Expected to be delicious. |
-| <a id="MyVeryDocumentedInfo-favorite_color"></a>favorite_color | A string representing my favorite color |
-
-
diff --git a/test/testdata/repo_rules_test/legacy_golden.md b/test/testdata/repo_rules_test/legacy_golden.md
deleted file mode 100644
index d705a32..0000000
--- a/test/testdata/repo_rules_test/legacy_golden.md
+++ /dev/null
@@ -1,24 +0,0 @@
-<!-- Generated with Stardoc: http://skydoc.bazel.build -->
-
-
-
-<a id="my_repo"></a>
-
-## my_repo
-
-<pre>
-my_repo(<a href="#my_repo-name">name</a>, <a href="#my_repo-repo_mapping">repo_mapping</a>, <a href="#my_repo-useless">useless</a>)
-</pre>
-
-Minimal example of a repository rule.
-
-**ATTRIBUTES**
-
-
-| Name | Description | Type | Mandatory | Default |
-| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="my_repo-name"></a>name | A unique name for this repository. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="my_repo-repo_mapping"></a>repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | |
-| <a id="my_repo-useless"></a>useless | This argument will be ignored.<br><br>You don't have to specify it, but you may. | String | optional | `"ignoreme"` |
-
-
diff --git a/update-release-binary.sh b/update-release-binary.sh
index 73e4334..ef25d17 100755
--- a/update-release-binary.sh
+++ b/update-release-binary.sh
@@ -13,36 +13,25 @@
# See the License for the specific language governing permissions and
# limitations under the License.
#
-# Renerates the Stardoc release binary from source in @io_bazel.
-#
-# This should only need to be run for cutting a new Stardoc release.
+# Updates vendored Stardoc output protos from @io_bazel git.
set -eu
-echo "** Building Stardoc from source..."
-bazel build --java_language_version=11 @io_bazel//src/main/java/com/google/devtools/build/skydoc:skydoc_deploy.jar
-
-echo "** Copying Stardoc binary..."
-cp bazel-bin/external/io_bazel/src/main/java/com/google/devtools/build/skydoc/skydoc_deploy.jar \
- stardoc/stardoc_binary.jar
-
-echo "** Stardoc copied."
-
echo "** Copying stardoc_output.proto from source..."
# Path of proto definition relative to Bazel source tree root
-PROTO_SRC=src/main/java/com/google/devtools/build/skydoc/rendering/proto/stardoc_output.proto
-# Path to @io_bazel repo on disk
-IO_BAZEL="$(bazel info output_base)/external/io_bazel"
-# Commit of @io_bazel's git_repository (generated by patch_cmds command in WORKSPACE)
-IO_BAZEL_SHA="$(cat ${IO_BAZEL}/.io_bazel.sha)"
-# Retrieve the first commit to modify ${PROTO_SRC} in the history of ${IO_BAZEL_SHA}
+PROTO_SRC=src/main/protobuf/stardoc_output.proto
+# Branch or commit in https://github.com/bazelbuild/bazel
+: "${BAZEL_BRANCH:=master}"
+# Retrieve the first commit to modify ${PROTO_SRC} in the history of ${BAZEL_BRANCH}
# using Github API; see https://docs.github.com/en/rest/commits/commits?apiVersion=2022-11-28
-# We need this because git_repository does a shallow clone, so our @io_bazel repo
-# does not have the git log for any given file.
PROTO_SRC_SHA="$(curl -s -L -H "Accept: application/vnd.github+json" \
- "https://api.github.com/repos/bazelbuild/bazel/commits?sha=${IO_BAZEL_SHA}&path=${PROTO_SRC}" \
+ "https://api.github.com/repos/bazelbuild/bazel/commits?sha=${BAZEL_BRANCH}&path=${PROTO_SRC}" \
| grep -m 1 '"sha":' | sed 's/.*"sha": "\(.*\)",.*/\1/')"
# Copy proto file and insert "Vendored from" slug immediately below the license.
-sed -e '/^\/\/ limitations under the License./ a //\n// Vendored from '"${PROTO_SRC}"'\n// in the Bazel source tree at commit '"${PROTO_SRC_SHA}" \
- "${IO_BAZEL}/${PROTO_SRC}" > stardoc/proto/stardoc_output.proto
+curl -s -L "https://raw.githubusercontent.com/bazelbuild/bazel/${PROTO_SRC_SHA}/${PROTO_SRC}" \
+ | sed '/^\/\/ limitations under the License./ a \
+//\
+// Vendored from '"${PROTO_SRC}"'\
+// in the Bazel source tree at commit '"${PROTO_SRC_SHA}n"'\
+' > stardoc/proto/stardoc_output.proto
echo "** stardoc_output.proto copied."
diff --git a/update-stardoc-docs.sh b/update-stardoc-docs.sh
index d4d7ce3..d1559bb 100755
--- a/update-stardoc-docs.sh
+++ b/update-stardoc-docs.sh
@@ -13,9 +13,7 @@
# See the License for the specific language governing permissions and
# limitations under the License.
#
-# Renerates the Stardoc rule documentation from source in @io_bazel.
-#
-# This should only need to be run for cutting a new Stardoc release.
+# Renerates the Stardoc rule documentation from source.
set -eu
diff --git a/update-stardoc-tests.sh b/update-stardoc-tests.sh
index 08af22c..b0152c1 100755
--- a/update-stardoc-tests.sh
+++ b/update-stardoc-tests.sh
@@ -35,25 +35,17 @@
# Allow users to override the bazel command with e.g. bazelisk.
: "${BAZEL:=bazel}"
-echo "** Verifying Bazel version..."
-if ! ${BAZEL} build --experimental_enable_starlark_doc_extract &> /dev/null; then
- echo >&2 "Please use a development version of Bazel, or Bazel 7 once it is released."
- echo >&2 "For example: USE_BAZEL_VERSION=last_green BAZEL=bazelisk ./update-stardoc-tests.sh"
- exit 1
-fi
-
# Some tests cannot be automatically regenerated using this script, as they don't fall under the normal
# golden test pattern
EXCLUDED_TESTS="namespace_test_with_allowlist|multi_level_namespace_test_with_allowlist|local_repository_test|stamping_with_stamping_off"
echo "** Querying for tests..."
-regen_legacy_targets=$(${BAZEL} query //test:all | grep regenerate_with_jar | grep -vE "_golden_stardoc|$EXCLUDED_TESTS")
-regen_starlark_doc_extract_targets=$(${BAZEL} query //test:all | grep regenerate_ | grep -vE "_legacy|_golden\.extract|$EXCLUDED_TESTS")
+regen_targets=$(${BAZEL} query //test:all | grep regenerate_ | grep -vE "_golden\.extract|$EXCLUDED_TESTS")
echo "** Building goldens..."
-${BAZEL} build $regen_legacy_targets $regen_starlark_doc_extract_targets
+${BAZEL} build $regen_targets
-echo "** Copying starlark_doc_extract goldens..."
-for regen_target in $regen_starlark_doc_extract_targets; do
+echo "** Copying goldens..."
+for regen_target in $regen_targets; do
base_target_name=$(echo $regen_target | sed 's/\/\/test://g')
testdata_pkg_name=$(echo $base_target_name | sed 's/regenerate_//g' | sed 's/_golden//g')
out_file="bazel-bin/test/${base_target_name}.out"
@@ -67,30 +59,6 @@
chmod 644 "${golden}"
done
-echo "** Copying legacy goldens..."
-for regen_target in $regen_legacy_targets; do
- base_target_name=$(echo $regen_target | sed 's/\/\/test://g')
- testdata_pkg_name=$(echo $base_target_name | sed 's/regenerate_with_jar_//g' | sed 's/_legacy_golden//g')
- out_file="bazel-bin/test/${base_target_name}.out"
- if [[ $regen_target == *"proto_format"* ]]; then
- ext="binaryproto"
- else
- ext="md"
- fi
- golden="test/testdata/${testdata_pkg_name}/golden.${ext}"
- legacy_golden="test/testdata/${testdata_pkg_name}/legacy_golden.${ext}"
- legacy_golden_target="${legacy_golden#test/}"
- if diff "${out_file}" "${golden}" > /dev/null; then
- # legacy_golden is no longer needed; we only need golden
- [[ -e "${legacy_golden}" ]] && rm "${legacy_golden}"
- run_buildozer "remove legacy_golden_file" "//test:${testdata_pkg_name}"
- else
- cp "${out_file}" "${legacy_golden}"
- chmod 644 "${legacy_golden}"
- run_buildozer "set legacy_golden_file \"${legacy_golden_target}\"" "//test:${testdata_pkg_name}"
- fi
-done
-
echo "** Files copied."
echo "Please note that not all golden files are correctly copied by this script."
echo "You may want to manually run:"
diff --git a/version.bzl b/version.bzl
index 9e7b7c6..7958a68 100644
--- a/version.bzl
+++ b/version.bzl
@@ -13,4 +13,4 @@
# limitations under the License.
"""The version of Stardoc."""
-version = "0.6.2"
+version = "0.7.0-pre"
