lucicfg/doc/templates/README.mdt

# 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}}

#### Arguments {#{{$sym.Anchor "args"}}}
{{range $sym.Doc.Args}}
* **{{.Name | EscapeMD}}**: {{.Desc | LinkifySymbols}}
{{- 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.
*/}}
{{ $meta := Symbol "@stdlib//builtins.star" "meta" }}
{{ $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 lucicfg itself
{{template "gen-funcs-doc" $meta}}

## 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}}