go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/lucicfg/starlark/stdlib/internal/luci/rules/console_view_entry.star (about)

     1  # Copyright 2019 The LUCI Authors.
     2  #
     3  # Licensed under the Apache License, Version 2.0 (the "License");
     4  # you may not use this file except in compliance with the License.
     5  # You may obtain a copy of the License at
     6  #
     7  #      http://www.apache.org/licenses/LICENSE-2.0
     8  #
     9  # Unless required by applicable law or agreed to in writing, software
    10  # distributed under the License is distributed on an "AS IS" BASIS,
    11  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  # See the License for the specific language governing permissions and
    13  # limitations under the License.
    14  
    15  """Defines luci.console_view_entry(...) rule."""
    16  
    17  load("@stdlib//internal/lucicfg.star", "lucicfg")
    18  load("@stdlib//internal/validate.star", "validate")
    19  load("@stdlib//internal/luci/common.star", "keys", "kinds", "view")
    20  
    21  def _console_view_entry(
    22          ctx,  # @unused
    23          builder = None,
    24          *,
    25          short_name = None,
    26          category = None,
    27          console_view = None):
    28      """A builder entry in some luci.console_view(...).
    29  
    30      Used inline in luci.console_view(...) declarations to provide `category` and
    31      `short_name` for a builder. `console_view` argument can be omitted in this
    32      case:
    33  
    34          luci.console_view(
    35              name = 'CI builders',
    36              ...
    37              entries = [
    38                  luci.console_view_entry(
    39                      builder = 'Windows Builder',
    40                      short_name = 'win',
    41                      category = 'ci',
    42                  ),
    43                  ...
    44              ],
    45          )
    46  
    47      Can also be used to declare that a builder belongs to a console outside of
    48      the console declaration. In particular useful in functions. For example:
    49  
    50          luci.console_view(name = 'CI builders')
    51  
    52          def ci_builder(name, ...):
    53            luci.builder(name = name, ...)
    54            luci.console_view_entry(console_view = 'CI builders', builder = name)
    55  
    56      Args:
    57        ctx: the implicit rule context, see lucicfg.rule(...).
    58        builder: a builder to add, see luci.builder(...). Can also be a reference
    59          to a builder defined in another project. See [Referring to builders in
    60          other projects](#external-builders) for more details.
    61        short_name: a shorter name of the builder. The recommendation is to keep
    62          this name as short as reasonable, as longer names take up more
    63          horizontal space.
    64        category: a string of the form `term1|term2|...` that describes the
    65          hierarchy of the builder columns. Neighboring builders with common
    66          ancestors will have their column headers merged. In expanded view, each
    67          leaf category or builder under a non-leaf category will have it's own
    68          column. The recommendation for maximum density is not to mix
    69          subcategories and builders for children of each category.
    70        console_view: a console view to add the builder to. Can be omitted if
    71          `console_view_entry` is used inline inside some luci.console_view(...)
    72          declaration.
    73      """
    74      return view.add_entry(
    75          kind = kinds.CONSOLE_VIEW_ENTRY,
    76          view = keys.console_view(console_view) if console_view else None,
    77          builder = builder,
    78          props = {
    79              "short_name": validate.string("short_name", short_name, required = False),
    80              "category": validate.string("category", category, required = False),
    81          },
    82      )
    83  
    84  console_view_entry = lucicfg.rule(impl = _console_view_entry)