| # LUCI configuration definition language |
| |
| {{/* Renders documentation for all functions in the given struct. */}} |
| {{define "gen-funcs-doc"}} |
| {{.Doc.Description | LinkifySymbols }} |
| |
| {{range $sym := .Symbols "func"}} |
| ### {{.FullName}} {#{{$sym.Anchor}}} |
| |
| ```python |
| {{$sym.InvocationSnippet}} |
| ``` |
| |
| {{if $sym.HasDocTag "advanced"}} |
| *** note |
| **Advanced function.** It is not used for common use cases. |
| *** |
| {{end}} |
| |
| {{$sym.Doc.Description | LinkifySymbols}} |
| {{if $sym.Doc.Args}} |
| #### Arguments {#{{$sym.Anchor "args"}}} |
| {{range $sym.Doc.Args}} |
| * **{{.Name | EscapeMD}}**: {{.Desc | LinkifySymbols}} |
| {{- end}} |
| {{- end}} |
| |
| {{if $sym.Doc.Returns}} |
| #### Returns {#{{$sym.Anchor "returns"}}} |
| |
| {{$sym.Doc.Returns | LinkifySymbols}} |
| {{end}} |
| |
| {{end}} |
| {{end}} |
| |
| |
| {{/* Renders TODO note. */}} |
| {{define "todo"}} |
| *** note |
| TODO: To be written. |
| *** |
| {{end}} |
| |
| |
| {{/* |
| Load all symbols we are going to document in advance to let LinkifySymbols |
| know that they can be referred to through anchors. |
| */}} |
| {{ $lucicfg := Symbol "@stdlib//builtins.star" "lucicfg" }} |
| {{ $time := Symbol "@stdlib//builtins.star" "time" }} |
| {{ $core := Symbol "@stdlib//builtins.star" "core" }} |
| {{ $acl := Symbol "@stdlib//builtins.star" "acl" }} |
| {{ $swarming := Symbol "@stdlib//builtins.star" "swarming" }} |
| {{ $scheduler := Symbol "@stdlib//builtins.star" "scheduler" }} |
| {{ $native := Symbol "@stdlib//native_doc.star" "" }} |
| {{ $proto := Symbol "@stdlib//proto_doc.star" "proto" }} |
| |
| |
| [TOC] |
| |
| ## Overview |
| |
| ### Working with lucicfg |
| {{template "todo"}} |
| |
| ### Concepts |
| {{template "todo"}} |
| |
| ### Resolving naming ambiguities |
| {{template "todo"}} |
| |
| ### Defining cron schedules {#schedules_doc} |
| {{template "todo"}} |
| |
| ## Configuring and inspecting lucicfg itself |
| {{template "gen-funcs-doc" $lucicfg}} |
| |
| ## Working with time |
| {{template "gen-funcs-doc" $time}} |
| |
| ## Core rules |
| {{template "gen-funcs-doc" $core}} |
| |
| ## ACLs |
| |
| ### Roles {#roles_doc} |
| |
| Below is the table with role constants that can be passed as `roles` in |
| {{LinkifySymbols "acl.entry(...)"}}. |
| |
| Due to some inconsistencies in how LUCI service are currently implemented, some |
| roles can be assigned only in {{LinkifySymbols "core.project(...)"}} rule, but |
| some also in individual {{LinkifySymbols "core.bucket(...)"}} rules. |
| |
| Similarly some roles can be assigned to individual users, other only to groups. |
| |
| | Role | Scope | Principals | Allows | |
| |-------|-------|------------|--------| |
| {{- range $sym := $acl.Symbols "var"}} |
| | {{.FullName}} | |
| {{- if .HasDocTag "project_level_only"}}project only{{else}}project, bucket{{end}} | |
| {{- if .HasDocTag "groups_only"}}groups{{else}}groups, users{{end}} | |
| {{- .Doc.Description | LinkifySymbols}} | |
| {{- end}} |
| |
| {{template "gen-funcs-doc" $acl}} |
| |
| ## Swarming |
| {{template "gen-funcs-doc" $swarming}} |
| |
| ## Scheduler |
| {{template "gen-funcs-doc" $scheduler}} |
| |
| ## Built-in constants and functions |
| |
| Refer to the list of [built-in constants and functions][starlark-builtins] |
| exposed in the global namespace by Starlark itself. |
| |
| [starlark-builtins]: https://github.com/google/starlark-go/blob/master/doc/spec.md#built-in-constants-and-functions |
| |
| In addition, `lucicfg` exposes the following functions. |
| |
| {{template "gen-funcs-doc" $native}} |
| {{template "gen-funcs-doc" $proto}} |