-
Notifications
You must be signed in to change notification settings - Fork 45
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Input .bzl files are turned into runfiles of a custom Stardoc binary, which allows reusing the Java runfiles library to load the files while taking repository mappings into account.
- Loading branch information
Showing
9 changed files
with
231 additions
and
210 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| 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") |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| load("@bazel_skylib//:bzl_library.bzl", "bzl_library") | ||
|
|
||
| bzl_library( | ||
| name = "stardoc_lib", | ||
| srcs = ["stardoc.bzl"], | ||
| visibility = ["//stardoc:__pkg__"], | ||
| deps = [ | ||
| "@bazel_skylib//:bzl_library", | ||
| ], | ||
| ) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,187 @@ | ||
| # Copyright 2018 The Bazel Authors. All rights reserved. | ||
| # | ||
| # Licensed under the Apache License, Version 2.0 (the "License"); | ||
| # you may not use this file except in compliance with the License. | ||
| # You may obtain a copy of the License at | ||
| # | ||
| # http://www.apache.org/licenses/LICENSE-2.0 | ||
| # | ||
| # Unless required by applicable law or agreed to in writing, software | ||
| # distributed under the License is distributed on an "AS IS" BASIS, | ||
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| # See the License for the specific language governing permissions and | ||
| # limitations under the License. | ||
|
|
||
| """Starlark rule for stardoc: a documentation generator tool written in Java.""" | ||
|
|
||
| load("@bazel_skylib//:bzl_library.bzl", "StarlarkLibraryInfo") | ||
|
|
||
| def _stardoc_runfiles_impl(ctx): | ||
| runfiles = ctx.runfiles( | ||
| files = [ctx.file.input], | ||
| transitive_files = depset(transitive = [ | ||
| dep[StarlarkLibraryInfo].transitive_srcs | ||
| for dep in ctx.attr.deps | ||
| ]), | ||
| ) | ||
| return [ | ||
| DefaultInfo(runfiles = runfiles), | ||
| ] | ||
|
|
||
| stardoc_runfiles = rule( | ||
| implementation = _stardoc_runfiles_impl, | ||
| attrs = { | ||
| "input": attr.label( | ||
| allow_single_file = [".bzl"], | ||
| ), | ||
| "deps": attr.label_list( | ||
| providers = [StarlarkLibraryInfo], | ||
| ), | ||
| }, | ||
| ) | ||
|
|
||
| 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 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_args = ctx.actions.args() | ||
| renderer_args.add("--input=" + str(proto_file.path)) | ||
| renderer_args.add("--output=" + str(ctx.outputs.out.path)) | ||
| renderer_args.add("--aspect_template=" + str(ctx.file.aspect_template.path)) | ||
| renderer_args.add("--header_template=" + str(ctx.file.header_template.path)) | ||
| renderer_args.add("--func_template=" + str(ctx.file.func_template.path)) | ||
| renderer_args.add("--provider_template=" + str(ctx.file.provider_template.path)) | ||
| renderer_args.add("--rule_template=" + str(ctx.file.rule_template.path)) | ||
| renderer = ctx.executable.renderer | ||
| ctx.actions.run( | ||
| outputs = [out_file], | ||
| inputs = [proto_file, ctx.file.aspect_template, ctx.file.header_template, ctx.file.func_template, ctx.file.provider_template, ctx.file.rule_template], | ||
| executable = renderer, | ||
| arguments = [renderer_args], | ||
| mnemonic = "Renderer", | ||
| progress_message = ("Converting proto format of %s to markdown format" % | ||
| (ctx.label.name)), | ||
| ) | ||
|
|
||
| # 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))] | ||
|
|
||
| stardoc = rule( | ||
| _stardoc_impl, | ||
| doc = """ | ||
| Generates documentation for exported skylark rule definitions in a target starlark file. | ||
| This rule is an experimental replacement for the existing skylark_doc rule. | ||
| """, | ||
| attrs = { | ||
| "input": attr.label( | ||
| doc = "The starlark file to generate documentation for.", | ||
| allow_single_file = [".bzl"], | ||
| ), | ||
| "format": attr.string( | ||
| doc = "The format of the output file. Valid values: 'markdown' or 'proto'.", | ||
| default = "markdown", | ||
| values = ["markdown", "proto"], | ||
| ), | ||
| "out": attr.output( | ||
| doc = "The (markdown) file to which documentation will be output.", | ||
| 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. | ||
| """, | ||
| default = [], | ||
| ), | ||
| "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". | ||
| """, | ||
| default = [], | ||
| ), | ||
| "stardoc": attr.label( | ||
| doc = "The location of the stardoc tool.", | ||
| allow_files = True, | ||
| cfg = "exec", | ||
| executable = True, | ||
| mandatory = True, | ||
| ), | ||
| "renderer": attr.label( | ||
| doc = "The location of the renderer tool.", | ||
| allow_files = True, | ||
| default = Label("//stardoc:renderer"), | ||
| cfg = "exec", | ||
| executable = True, | ||
| ), | ||
| "aspect_template": attr.label( | ||
| doc = "The input file template for generating documentation of aspects.", | ||
| allow_single_file = [".vm"], | ||
| default = Label("//stardoc:templates/markdown_tables/aspect.vm"), | ||
| ), | ||
| "header_template": attr.label( | ||
| doc = "The input file template for the header of the output documentation.", | ||
| allow_single_file = [".vm"], | ||
| default = Label("//stardoc:templates/markdown_tables/header.vm"), | ||
| ), | ||
| "func_template": attr.label( | ||
| doc = "The input file template for generating documentation of functions.", | ||
| allow_single_file = [".vm"], | ||
| default = Label("//stardoc:templates/markdown_tables/func.vm"), | ||
| ), | ||
| "provider_template": attr.label( | ||
| doc = "The input file template for generating documentation of providers.", | ||
| allow_single_file = [".vm"], | ||
| default = Label("//stardoc:templates/markdown_tables/provider.vm"), | ||
| ), | ||
| "rule_template": attr.label( | ||
| doc = "The input file template for generating documentation of rules.", | ||
| allow_single_file = [".vm"], | ||
| default = Label("//stardoc:templates/markdown_tables/rule.vm"), | ||
| ), | ||
| }, | ||
| ) |
Binary file not shown.
Oops, something went wrong.