Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add support for Bzlmod #141

Merged
merged 13 commits into from
May 5, 2023
Merged

Add support for Bzlmod #141

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
85806b0
Add support for Bzlmod
fmeum Nov 16, 2022
5852aee
Fix buildifier warnings
fmeum Dec 12, 2022
1e2fb34
Fix generated files
fmeum Mar 8, 2023
a665293
Remove stardoc_runfiles
fmeum Mar 8, 2023
a025227
Apply buildifier fixes
fmeum Mar 8, 2023
505677f
TMP: Use compatible Bazel commit
fmeum Mar 8, 2023
8cd0d2f
Address review comments
fmeum Apr 27, 2023
95f18a1
Address next round of comments
fmeum Apr 28, 2023
dcd2d8b
Remove unused deps
fmeum Apr 28, 2023
bf6632e
Allow stardoc to be a java_binary or jar
fmeum Apr 28, 2023
9f7b550
Add missing Bzlmod dep on rules_license
fmeum Apr 28, 2023
0e6bb20
Revert "Allow stardoc to be a java_binary or jar"
fmeum Apr 28, 2023
dd785dd
rebuilt jars on trusted machine
tetromino May 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions MODULE.bazel
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
module(
name = "stardoc",
version = "0.5.3",
compatibility_level = 1,
)

bazel_dep(name = "bazel_skylib", version = "1.2.1")
bazel_dep(name = "rules_java", version = "5.3.5")
bazel_dep(name = "rules_license", version = "0.0.3")
80 changes: 70 additions & 10 deletions WORKSPACE
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,8 @@ load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
# Needed for generating the Stardoc release binary.
git_repository(
name = "io_bazel",
commit = "901c75e459d737220cb8e29649c1b6ba24e2221d", # Sep 27, 2022
patches = ["@//:bazel.patch"], # TODO: Remove after next bazel update
commit = "c6a8c0827061697fa8fa9dd21310b276d9887e8c", # 2023-04-27
remote = "https://github.com/bazelbuild/bazel.git",
shallow_since = "1664304093 -0700",
)

# The following binds are needed for building protobuf java libraries.
Expand All @@ -36,6 +34,68 @@ bind(
actual = "@io_bazel//third_party:error_prone_annotations",
)

RULES_JVM_EXTERNAL_TAG = "4.5"

RULES_JVM_EXTERNAL_SHA = "b17d7388feb9bfa7f2fa09031b32707df529f26c91ab9e5d909eb1676badd9a6"

http_archive(
name = "rules_jvm_external",
sha256 = RULES_JVM_EXTERNAL_SHA,
strip_prefix = "rules_jvm_external-%s" % RULES_JVM_EXTERNAL_TAG,
url = "https://github.com/bazelbuild/rules_jvm_external/archive/refs/tags/%s.zip" % RULES_JVM_EXTERNAL_TAG,
)

load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps")

rules_jvm_external_deps()

load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup")

rules_jvm_external_setup()

load("@rules_jvm_external//:defs.bzl", "maven_install")

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 = "//:maven_install.json",
repositories = [
"https://repo1.maven.org/maven2",
],
strict_visibility = True,
)

load("@maven//:defs.bzl", "pinned_maven_install")

pinned_maven_install()

# Needed only because of java_tools.
http_archive(
name = "rules_cc",
Expand All @@ -48,11 +108,11 @@ http_archive(
)

# Needed as a transitive dependency of @io_bazel
git_repository(
http_archive(
name = "rules_python",
commit = "4b84ad270387a7c439ebdccfd530e2339601ef27",
remote = "https://github.com/bazelbuild/rules_python.git",
shallow_since = "1564776078 -0400",
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
Expand All @@ -72,10 +132,10 @@ rules_pkg_dependencies()
# Needed as a transitive dependency of @io_bazel
http_archive(
name = "rules_proto",
sha256 = "9850fcf6ad40fa348e6f13b2cfef4bb4639762f804794f2bf61d988f4ba0dae9",
strip_prefix = "rules_proto-4.0.0-3.19.2-2",
sha256 = "dc3fb206a2cb3441b485eb1e423165b231235a1ea9b031b4433cf7bc1fa460dd",
strip_prefix = "rules_proto-5.3.0-21.7",
urls = [
"https://github.com/bazelbuild/rules_proto/archive/refs/tags/4.0.0-3.19.2-2.tar.gz",
"https://github.com/bazelbuild/rules_proto/archive/refs/tags/5.3.0-21.7.tar.gz",
],
)

Expand Down
14 changes: 0 additions & 14 deletions bazel.patch
View file
Open in desktop

This file was deleted.

51 changes: 24 additions & 27 deletions docs/stardoc_rule.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,34 +7,31 @@ Starlark rule for stardoc: a documentation generator tool written in Java.
## stardoc

<pre>
stardoc(<a href="#stardoc-name">name</a>, <a href="#stardoc-aspect_template">aspect_template</a>, <a href="#stardoc-deps">deps</a>, <a href="#stardoc-format">format</a>, <a href="#stardoc-func_template">func_template</a>, <a href="#stardoc-header_template">header_template</a>, <a href="#stardoc-input">input</a>, <a href="#stardoc-out">out</a>,
<a href="#stardoc-provider_template">provider_template</a>, <a href="#stardoc-renderer">renderer</a>, <a href="#stardoc-rule_template">rule_template</a>, <a href="#stardoc-semantic_flags">semantic_flags</a>, <a href="#stardoc-stardoc">stardoc</a>, <a href="#stardoc-symbol_names">symbol_names</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-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-provider_template">provider_template</a>, <a href="#stardoc-rule_template">rule_template</a>, <a href="#stardoc-kwargs">kwargs</a>)
</pre>


Generates documentation for exported skylark rule definitions in a target starlark file.

This rule is an experimental replacement for the existing skylark_doc rule.


**ATTRIBUTES**


| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="stardoc-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="stardoc-aspect_template"></a>aspect_template | The input file template for generating documentation of aspects. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//stardoc:templates/markdown_tables/aspect.vm</code> |
| <a id="stardoc-deps"></a>deps | A list of bzl_library dependencies which the input depends on. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
| <a id="stardoc-format"></a>format | The format of the output file. Valid values: 'markdown' or 'proto'. | String | optional | <code>"markdown"</code> |
| <a id="stardoc-func_template"></a>func_template | The input file template for generating documentation of functions. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//stardoc:templates/markdown_tables/func.vm</code> |
| <a id="stardoc-header_template"></a>header_template | The input file template for the header of the output documentation. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//stardoc:templates/markdown_tables/header.vm</code> |
| <a id="stardoc-input"></a>input | The starlark file to generate documentation for. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> |
| <a id="stardoc-out"></a>out | The (markdown) file to which documentation will be output. | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
| <a id="stardoc-provider_template"></a>provider_template | The input file template for generating documentation of providers. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//stardoc:templates/markdown_tables/provider.vm</code> |
| <a id="stardoc-renderer"></a>renderer | The location of the renderer tool. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//stardoc:renderer</code> |
| <a id="stardoc-rule_template"></a>rule_template | The input file template for generating documentation of rules. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//stardoc:templates/markdown_tables/rule.vm</code> |
| <a id="stardoc-semantic_flags"></a>semantic_flags | 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.<br><br>For example, if <code>//foo:bar.bzl</code> does not build except when a user would specify <code>--incompatible_foo_semantic=false</code>, then this attribute should contain "--incompatible_foo_semantic=false". | List of strings | optional | <code>[]</code> |
| <a id="stardoc-stardoc"></a>stardoc | The location of the stardoc tool. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//stardoc:stardoc</code> |
| <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. | List of strings | optional | <code>[]</code> |
Generates documentation for exported starlark rule definitions in a target starlark file.

**PARAMETERS**


| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="stardoc-name"></a>name | The name of the stardoc target. | none |
| <a id="stardoc-input"></a>input | The starlark file to generate documentation for (mandatory). | none |
| <a id="stardoc-out"></a>out | The file to which documentation will be output (mandatory). | none |
| <a id="stardoc-deps"></a>deps | A list of bzl_library dependencies which the input depends on. | <code>[]</code> |
| <a id="stardoc-format"></a>format | The format of the output file. Valid values: 'markdown' or 'proto'. | <code>"markdown"</code> |
| <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. | <code>[]</code> |
| <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 <code>//foo:bar.bzl</code> does not build except when a user would specify <code>--incompatible_foo_semantic=false</code>, then this attribute should contain "--incompatible_foo_semantic=false". | <code>[]</code> |
| <a id="stardoc-stardoc"></a>stardoc | The location of the stardoc tool. | <code>Label("//stardoc:prebuilt_stardoc_binary")</code> |
| <a id="stardoc-renderer"></a>renderer | The location of the renderer tool. | <code>Label("//stardoc:renderer")</code> |
| <a id="stardoc-aspect_template"></a>aspect_template | The input file template for generating documentation of aspects | <code>Label("//stardoc:templates/markdown_tables/aspect.vm")</code> |
| <a id="stardoc-func_template"></a>func_template | The input file template for generating documentation of functions. | <code>Label("//stardoc:templates/markdown_tables/func.vm")</code> |
| <a id="stardoc-header_template"></a>header_template | The input file template for the header of the output documentation. | <code>Label("//stardoc:templates/markdown_tables/header.vm")</code> |
| <a id="stardoc-provider_template"></a>provider_template | The input file template for generating documentation of providers. | <code>Label("//stardoc:templates/markdown_tables/provider.vm")</code> |
| <a id="stardoc-rule_template"></a>rule_template | The input file template for generating documentation of rules. | <code>Label("//stardoc:templates/markdown_tables/rule.vm")</code> |
| <a id="stardoc-kwargs"></a>kwargs | Further arguments to pass to stardoc. | none |


Loading