Skip to content

feat: Add stardocs #45

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

Open
alexeagle wants to merge 2 commits into
base: main
Choose a base branch
from
+80 −78
Open

feat: Add stardocs #45

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
44fa8bd
add stardocs
alexeagle Feb 9, 2026
a1849e9
fix: use markdown for docstrings, not HTML
alexeagle Feb 10, 2026
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
13 changes: 13 additions & 0 deletions shell/BUILD
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,16 @@ bzl_library(
visibility = ["//visibility:public"],
deps = ["//shell/private:private_bzl"],
)

[
starlark_doc_extract(
name = module + ".doc_extract",
src = module + ".bzl",
deps = [":rules_bzl"],
)
for module in [
"sh_binary",
"sh_library",
"sh_test",
]
]
38 changes: 19 additions & 19 deletions shell/private/sh_binary.bzl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,25 +21,25 @@ visibility("public")

sh_binary = make_sh_executable_rule(
doc = """
<p>
The <code>sh_binary</code> rule is used to declare executable shell scripts.
(<code>sh_binary</code> is a misnomer: its outputs aren't necessarily binaries.) This rule ensures
that all dependencies are built, and appear in the <code>runfiles</code> area at execution time.
We recommend that you name your <code>sh_binary()</code> rules after the name of the script minus
the extension (e.g. <code>.sh</code>); the rule name and the file name must be distinct.
<code>sh_binary</code> respects shebangs, so any available interpreter may be used (eg.
<code>#!/bin/zsh</code>)
</p>
<h4 id="sh_binary_examples">Example</h4>
<p>For a simple shell script with no dependencies and some data files:
</p>
<pre class="code">
sh_binary(
name = "foo",
srcs = ["foo.sh"],
data = glob(["datafiles/*.txt"]),
)
</pre>
The `sh_binary` rule is used to declare executable shell scripts.
(`sh_binary` is a misnomer: its outputs aren't necessarily binaries.) This rule ensures
that all dependencies are built, and appear in the `runfiles` area at execution time.
We recommend that you name your `sh_binary()` rules after the name of the script minus
the extension (e.g. `.sh`); the rule name and the file name must be distinct.
`sh_binary` respects shebangs, so any available interpreter may be used (eg.
`#!/bin/zsh`)

#### Example

For a simple shell script with no dependencies and some data files:

```starlark
sh_binary(
name = "foo",
srcs = ["foo.sh"],
data = glob(["datafiles/*.txt"]),
)
```
""",
executable = True,
)
26 changes: 12 additions & 14 deletions shell/private/sh_executable.bzl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,12 +187,11 @@ def make_sh_executable_rule(doc, extra_attrs = {}, **kwargs):
allow_files = True,
doc = """
The file containing the shell script.
<p>
This attribute must be a singleton list, whose element is the shell script.
This script must be executable, and may be a source file or a generated file.
All other files required at runtime (whether scripts or data) belong in the
<code>data</code> attribute.
</p>

This attribute must be a singleton list, whose element is the shell script.
This script must be executable, and may be a source file or a generated file.
All other files required at runtime (whether scripts or data) belong in the
`data` attribute.
""",
),
"data": attr.label_list(
Expand All @@ -203,14 +202,13 @@ The file containing the shell script.
allow_rules = ["sh_library"],
doc = """
The list of "library" targets to be aggregated into this target.
See general comments about <code>deps</code>
at <a href="${link common-definitions#typical.deps}">Typical attributes defined by
most build rules</a>.
<p>
This attribute should be used to list other <code>sh_library</code> rules that provide
interpreted program source code depended on by the code in <code>srcs</code>. The files
provided by these rules will be present among the <code>runfiles</code> of this target.
</p>
See general comments about `deps` at
[Typical attributes defined by most build rules](https://bazel.build/reference/be/common-definitions#typical.deps)

This attribute should be used to list other `sh_library` rules that provide
interpreted program source code depended on by the code in `srcs`. The files
provided by these rules will be present among the `runfiles` of this target.

""",
),
"_runfiles_dep": attr.label(
Expand Down
69 changes: 30 additions & 39 deletions shell/private/sh_library.bzl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,54 +46,47 @@ def _sh_library_impl(ctx):
sh_library = rule(
_sh_library_impl,
doc = """
<p>
The main use for this rule is to aggregate together a logical
"library" consisting of related scripts&mdash;programs in an
interpreted language that does not require compilation or linking,
such as the Bourne shell&mdash;and any data those programs need at
run-time. Such "libraries" can then be used from
the <code>data</code> attribute of one or
more <code>sh_binary</code> rules.
</p>
The main use for this rule is to aggregate together a logical
"library" consisting of related scripts -- programs in an
interpreted language that does not require compilation or linking,
such as the Bourne shell -- and any data those programs need at
run-time. Such "libraries" can then be used from
the `data` attribute of one or
more `sh_binary` rules.

<p>
You can use the <a href="${link filegroup}"><code>filegroup</code></a> rule to aggregate data
files.
</p>
You can use the [filegroup](https://bazel.build/reference/be/general#filegroup)
rule to aggregate data files.

<p>
In interpreted programming languages, there's not always a clear
distinction between "code" and "data": after all, the program is
just "data" from the interpreter's point of view. For this reason
this rule has three attributes which are all essentially equivalent:
<code>srcs</code>, <code>deps</code> and <code>data</code>.
The current implementation does not distinguish between the elements of these lists.
All three attributes accept rules, source files and generated files.
It is however good practice to use the attributes for their usual purpose (as with other rules).
</p>
In interpreted programming languages, there's not always a clear
distinction between "code" and "data": after all, the program is
just "data" from the interpreter's point of view. For this reason
this rule has three attributes which are all essentially equivalent:
`srcs`, `deps` and `data`.
The current implementation does not distinguish between the elements of these lists.
All three attributes accept rules, source files and generated files.
It is however good practice to use the attributes for their usual purpose (as with other rules).

<h4 id="sh_library_examples">Examples</h4>
#### Examples

<pre class="code">
```starlark
sh_library(
name = "foo",
data = [
":foo_service_script", # an sh_binary with srcs
":deploy_foo", # another sh_binary with srcs
],
)
</pre>
```
""",
attrs = {
"srcs": attr.label_list(
allow_files = True,
doc = """
The list of input files.
<p>
This attribute should be used to list shell script source files that belong to
this library. Scripts can load other scripts using the shell's <code>source</code>
or <code>.</code> command.
</p>

This attribute should be used to list shell script source files that belong to
this library. Scripts can load other scripts using the shell's `source`
or `.` command.
""",
),
"data": attr.label_list(
Expand All @@ -104,14 +97,12 @@ The list of input files.
allow_rules = ["sh_library"],
doc = """
The list of "library" targets to be aggregated into this target.
See general comments about <code>deps</code>
at <a href="${link common-definitions#typical.deps}">Typical attributes defined by
most build rules</a>.
<p>
This attribute should be used to list other <code>sh_library</code> rules that provide
interpreted program source code depended on by the code in <code>srcs</code>. The files
provided by these rules will be present among the <code>runfiles</code> of this target.
</p>
See general comments about `deps` at
[Typical attributes defined by most build rules](https://bazel.build/reference/be/common-definitions#typical.deps).

This attribute should be used to list other `sh_library` rules that provide
interpreted program source code depended on by the code in `srcs`. The files
provided by these rules will be present among the `runfiles` of this target.
""",
),
},
Expand Down
12 changes: 6 additions & 6 deletions shell/private/sh_test.bzl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,22 +21,22 @@ visibility("public")

sh_test = make_sh_executable_rule(
doc = """
<p>A <code>sh_test()</code> rule creates a test written as a Bourne shell script.</p>
A `sh_test()` rule creates a test written as a Bourne shell script.

<p>See the <a href="${link common-definitions#common-attributes-tests}">
attributes common to all test rules (*_test)</a>.</p>
See the
[attributes common to all test rules (*_test)](https://bazel.build/reference/be/common-definitions#common-attributes-tests).

<h4 id="sh_test_examples">Examples</h4>
#### Examples

<pre class="code">
```
sh_test(
name = "foo_integration_test",
size = "small",
srcs = ["foo_integration_test.sh"],
deps = [":foo_sh_lib"],
data = glob(["testdata/*.txt"]),
)
</pre>
```
""",
test = True,
fragments = ["coverage"],
Expand Down