From f8e9051117e59ddfe2119f41344622094879e632 Mon Sep 17 00:00:00 2001 From: Alex Tercete Date: Fri, 17 Jan 2025 10:38:55 +0000 Subject: [PATCH 1/7] docs(config): update description and examples --- labgrid/config/rule.bzl | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/labgrid/config/rule.bzl b/labgrid/config/rule.bzl index 1cffe630..ede3586c 100644 --- a/labgrid/config/rule.bzl +++ b/labgrid/config/rule.bzl @@ -4,23 +4,21 @@ load("@rules_python//python:defs.bzl", "PyInfo") visibility("//...") DOC = """ -Binds a LabGrid configuration file to the associated data required to setup, load and teardown the LabGrid environment. +Binds a labgrid configuration file to the associated data required to setup, load and teardown the labgrid environment. ```py labgrid_config( name = "config", src = "docker.yaml", env = { - "LG_STATE": "accessible" - "LG_ENV": "$(location :config.yaml)" + "LG_ENV": "$(location :docker.yaml)" }, - data = ["config.yaml"] deps = ["@pip//:docker"], ) toolchain( name = "docker", - target_compatible_with = ["//labgrid/constraint:docker"], + target_compatible_with = ["//constraint:docker"], toolchain = ":config", toolchain_type = "@rules_labgrid//labgrid/toolchain/config:type", ) @@ -28,8 +26,11 @@ toolchain( A tool can resolve the attributes via the late-bound labels: -- `@rules_labgrid//labgrid/config:src` +- `@rules_labgrid//labgrid/config:data` - `@rules_labgrid//labgrid/config:deps` +- `@rules_labgrid//labgrid/config:env` +- `@rules_labgrid//labgrid/config:managers` +- `@rules_labgrid//labgrid/config:tools` For example, a tool that works with `labgrid_genrule`: @@ -44,7 +45,7 @@ labgrid_genrule( name = "gen", cmd = "$(location :example)", tools = [":example"], - platform = "///labgrid/platform:docker", + platform = "//platform:docker", ) ``` @@ -53,35 +54,35 @@ The `deps` label will be resolved to the correct Python depedendencies needed to ATTRS = { "src": attr.label( - doc = "The LabGrid configuration YAML.", + doc = "The labgrid configuration YAML.", allow_single_file = [".yml", ".yaml"], ), "deps": attr.label_list( - doc = "LabGrid configuration Python dependencies.", + doc = "The labgrid configuration Python dependencies.", providers = [[DefaultInfo, PyInfo]], cfg = "exec", ), "env": attr.string_dict( - doc = "The environment variables to set. Subject to `$(location)` and \"Make\" variable substitution.", + doc = "The environment variables to set for the configuration. Subject to `$(location)` and \"Make\" variable substitution.", ), "state": attr.label( - doc = "The state of the configuration.", + doc = "The states to transition the configuration strategy to.", providers = [LabgridStateInfo], ), "data": attr.label_list( allow_files = True, - doc = "The data files to use.", + doc = "The data files to use in the configuration.", providers = [DefaultInfo], cfg = "target", ), "tools": attr.label_list( allow_files = True, - doc = "The tools to use.", + doc = "The tools to use in the configuration.", providers = [DefaultInfo], cfg = "exec", ), "managers": attr.label_list( - doc = "A context manager that `//labgrid/executor` will use that sets up the LabGrid environment.", + doc = "A list of Python context managers to customize the setup of the labgrid environment.", providers = [[DefaultInfo, PyInfo]], cfg = "exec", ), -- GitLab From d8a7d3b767ee5f153a8077fca911b3e72552afdf Mon Sep 17 00:00:00 2001 From: Alex Tercete Date: Fri, 17 Jan 2025 11:29:57 +0000 Subject: [PATCH 2/7] docs(config_toolchain): add description --- labgrid/config/toolchain/macro.bzl | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/labgrid/config/toolchain/macro.bzl b/labgrid/config/toolchain/macro.bzl index b8a308ef..ed2cb810 100644 --- a/labgrid/config/toolchain/macro.bzl +++ b/labgrid/config/toolchain/macro.bzl @@ -3,6 +3,21 @@ load("@rules_labgrid//labgrid/config:defs.bzl", "labgrid_config") visibility("//...") def labgrid_config_toolchain(*, name, src, target_compatible_with, exec_compatible_with = [], state = "@rules_labgrid//labgrid/state", managers = [], deps = [], env = {}, data = [], tools = [], toolchains = []): + """Registers a labgrid configuration as a toolchain of type `@rules_labgrid//labgrid/toolchain/config:type`. + + Args: + name: A unique name for this rule. + src: The labgrid configuration YAML. + target_compatible_with: The constraints to set for the target. + exec_compatible_with: The constraints to set for the exec. + state: The states to transition the configuration strategy to + managers: A list of Python context managers to customize the setup of the labgrid environment. + deps: The labgrid configuration Python dependencies. + env: The environment variables to set for the configuration. `LG_ENV` is always set to the path of `src`. Subject to `$(location)` and \"Make\" variable substitution. + data: The data files to use in the configuration. + tools: The tools to use in the configuration. + toolchains: The toolchains to use in the configuration. + """ src = native.package_relative_label(src) labgrid_config( name = "{}-config".format(name), -- GitLab From 180c2664ef4908dda6d0f625ff302183694e3148 Mon Sep 17 00:00:00 2001 From: Alex Tercete Date: Fri, 17 Jan 2025 11:41:15 +0000 Subject: [PATCH 3/7] docs(genrule): update description --- labgrid/genrule/rule.bzl | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/labgrid/genrule/rule.bzl b/labgrid/genrule/rule.bzl index 827ffcfd..5192e959 100644 --- a/labgrid/genrule/rule.bzl +++ b/labgrid/genrule/rule.bzl @@ -3,16 +3,16 @@ load("//labgrid/cfg:store.bzl", _cfg = "store") visibility("//...") -DOC = """Executes a Shell command on the host within a LabGrid environment. +DOC = """Executes a Shell command on the host within a labgrid environment. -The "@rules_labgrid//labgrid/toolchain/executor:type` toolchain is used to create the environment that the command runs under. +The "@rules_labgrid//labgrid/toolchain/config:type` toolchain is used to set up the environment that the command runs under. `@ape//:bash` is used to provide a hermetic, consistent, shell environment for the command. """ ATTRS = { "cmd": attr.string( - doc = "A Shell command to run on the executor within the LabGrid environment.", + doc = "A Shell command to run within the labgrid environment.", mandatory = True, # configurable = True, # TODO: Bazel 8+ ), @@ -22,7 +22,7 @@ ATTRS = { allow_files = True, ), "tools": attr.label_list( - doc = "A list of tools for this rule, that will run on the executor.", + doc = "A list of tools for this rule.", cfg = "exec", ), "outs": attr.output_list( @@ -35,7 +35,7 @@ ATTRS = { providers = [platform_common.PlatformInfo], ), "_executor": attr.label( - doc = "The LabGrid environment executor", + doc = "The labgrid environment executor", default = "//labgrid/executor", executable = True, cfg = "exec", -- GitLab From e5da7c9b1da2bfed88c885dce3c1beb5d7637383 Mon Sep 17 00:00:00 2001 From: Alex Tercete Date: Fri, 17 Jan 2025 11:43:06 +0000 Subject: [PATCH 4/7] docs(run_binary): update description --- labgrid/run/binary/rule.bzl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/labgrid/run/binary/rule.bzl b/labgrid/run/binary/rule.bzl index 28ea2726..c1fb1ff3 100644 --- a/labgrid/run/binary/rule.bzl +++ b/labgrid/run/binary/rule.bzl @@ -2,7 +2,7 @@ load("//labgrid/cfg:store.bzl", _cfg = "store") visibility("//...") -DOC = """Executes a binary on the host within a LabGrid environment.""" +DOC = """Executes a binary on the host within a labgrid environment.""" ATTRS = { "tool": attr.label( @@ -41,7 +41,7 @@ ATTRS = { providers = [platform_common.PlatformInfo], ), "_executor": attr.label( - doc = "The LabGrid environment executor", + doc = "The labgrid environment executor", default = "//labgrid/executor", executable = True, cfg = "exec", -- GitLab From c00c798e0edf5b9055e3189557479f07579cb2cf Mon Sep 17 00:00:00 2001 From: Alex Tercete Date: Fri, 17 Jan 2025 11:48:09 +0000 Subject: [PATCH 5/7] docs(test): update description --- labgrid/test/rule.bzl | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/labgrid/test/rule.bzl b/labgrid/test/rule.bzl index 46f97f65..ce4b84de 100644 --- a/labgrid/test/rule.bzl +++ b/labgrid/test/rule.bzl @@ -2,11 +2,14 @@ load("//labgrid/cfg:store.bzl", _cfg = "store") visibility("//...") -DOC = """Run a test executable on the device.""" +DOC = """Run a test executable on the device. + +The test executable and its dependencies are transferred to the device using the implementation of `CommandProtocol` specified in the labgrid configuration. +""" ATTRS = { "src": attr.label( - doc = "The test executable to run on the Labgrid device", + doc = "The test executable to run on the labgrid device", executable = True, cfg = "target", ), @@ -15,13 +18,13 @@ ATTRS = { providers = [platform_common.PlatformInfo], ), "_executor": attr.label( - doc = "The LabGrid environment executor", + doc = "The labgrid environment executor", default = "//labgrid/executor", executable = True, cfg = "exec", ), "_run": attr.label( - doc = "The LabGrid run", + doc = "The labgrid run", default = "//labgrid/run", executable = True, cfg = "exec", -- GitLab From 704ae18aa26a57ec9e857295fa41f0d919a5c4ab Mon Sep 17 00:00:00 2001 From: Alex Tercete Date: Fri, 17 Jan 2025 11:50:55 +0000 Subject: [PATCH 6/7] docs(state): update description --- labgrid/state/rule.bzl | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/labgrid/state/rule.bzl b/labgrid/state/rule.bzl index 303ca12d..1aec06f8 100644 --- a/labgrid/state/rule.bzl +++ b/labgrid/state/rule.bzl @@ -3,18 +3,18 @@ load(":StateInfo.bzl", "StateInfo") visibility("//labgrid/state/...") -DOC = "A rule to create a StateInfo object." +DOC = "Creates a StateInfo instance." ATTRS = { "initial": attr.string( - doc = "The initial state of the configuration.", + doc = "The initial state of the configuration strategy.", ), "desired": attr.string( - doc = "The desired state of the configuration.", + doc = "The desired state of the configuration strategy.", mandatory = True, ), "final": attr.string( - doc = "The final state of the configuration.", + doc = "The final state of the configuration strategy.", ), } -- GitLab From e04084737561a5b5d4a7b8ee1a1447e507d73d45 Mon Sep 17 00:00:00 2001 From: Alex Tercete Date: Fri, 17 Jan 2025 15:19:21 +0000 Subject: [PATCH 7/7] docs(run_binary): include in generation --- docs/BUILD.bazel | 1 + labgrid/run/binary/BUILD.bazel | 9 +++++++++ 2 files changed, 10 insertions(+) diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel index 2c1efaf7..0bead632 100644 --- a/docs/BUILD.bazel +++ b/docs/BUILD.bazel @@ -7,6 +7,7 @@ filegroup( "index.html", "index.mjs", "//labgrid/genrule:docs", + "//labgrid/run/binary:docs", "//labgrid/test:docs", ], ) diff --git a/labgrid/run/binary/BUILD.bazel b/labgrid/run/binary/BUILD.bazel index 8c152c42..a19a176e 100644 --- a/labgrid/run/binary/BUILD.bazel +++ b/labgrid/run/binary/BUILD.bazel @@ -1,4 +1,5 @@ load("@bazel_skylib//:bzl_library.bzl", "bzl_library") +load("@stardoc//stardoc:html_tables_stardoc.bzl", stardoc = "html_tables_stardoc") bzl_library( name = "defs", @@ -13,3 +14,11 @@ bzl_library( visibility = ["//visibility:public"], deps = ["//labgrid/cfg:store"], ) + +stardoc( + name = "docs", + out = "defs.html", + input = "defs.bzl", + visibility = ["//:__subpackages__"], + deps = [":defs"], +) -- GitLab