Merge pull request #172 from synyx/multidash-docs

documentation, describe multi-dashboard feature

README.md

@@ -46,6 +46,9 @@ at `/etc/tuwat.d`.
 
 The files have to end with `.toml`, the basename will be used as dashboard name.
 
+For further examples and more information on dashboards, see the
+[dashboard documentation](docs/dashboards.md).
+
 ### Rules
 
 The rule-system works via an exclude list, matching rules simply exclude items.
@@ -58,40 +61,7 @@ description = "blocked because not needed"
 what = "fooo service"
 ```
 
-* The `description` field provides a visible explanation, why the item is
-  excluded.
-* The `what` field selects all items where the `What` matches the given
-  regular expression.
-
-```toml
-[[rule]]
-description = "Ignore Drafts"
-what = "Thing"
-when = "> 60"
-[rule.label]
-Draft = "true"
-```
-
-* The `label` section selects items via labels.  In this example it would match
-  an item which has the label `Draft` which matches the given regular expression.
-* The label rules will combine as `AND`.
-* `what` rules will combine as `AND` with label rules.
-* `when` rules will combine with `AND` with label and `what` rules.
-
-#### Matching Rules
-
-The default is to match the value in the configuration as a regular expression.
-However, this can be changed by specifying an operator.
-
-* `~= string`: Explicitly require a regular expression to be matched
-* `=  string`: Require the string to exactly match.  In case the value is
-  numeric, this will mean that the value will compared like a floating point
-  value.  This means that differences below `1e-8` will be considered to be
-  the same.
-* `>  number`: Require both configuration and the value in the alert to be a
-  numerical value and that the value in the alert to be bigger than the
-  configured number.
-  This also applies to the `<`, `>=`, `<=` operators.
+For more information, see the [rule documentation](docs/rules.md).
 
 ## License
 
@@ -109,6 +79,12 @@ export TUWAT_TEMPLATEDIR= TUWAT_STATICDIR=
 
 * Open http://localhost:8988
 
+Setting `TUWAT_TEMPLATEDIR` and `TUWAT_STATICDIR` to empty will
+automatically use the development directories (`pkg/web/templates`
+and `pkg/web/static` respectively).
+Not declaring the template/static directory means that the
+versions bundled into the binary are used.
+
 ### Adding a new collector
 
 * See `pkg/connectors/example` for a very basic example on how a connector

docs/config/dashboards/drafts.toml

@@ -0,0 +1,7 @@
+[main]
+mode = "include"
+
+[[rule]]
+description = "Show only drafts"
+[rule.label]
+Draft = "true"

docs/config/dashboards/no-drafts.toml

@@ -0,0 +1,4 @@
+[[rule]]
+description = "Ignore Drafts"
+[rule.label]
+Draft = "true"

docs/dashboards.md

@@ -0,0 +1,72 @@
+# Dashboards
+
+## Single Dashboard
+
+To only show a single dashboard, simply add all configuration
+and rules in the main `config.toml`.
+
+### Example
+
+`tuwat -conf config.toml`
+
+```toml
+[[rule]]
+description = "Ignore Drafts"
+[rule.label]
+Draft = "true"
+
+[[github]]
+Repos = ['synyx/tuwat', 'synyx/buchungsstreber']
+Tag = 'gh'
+```
+
+
+### Dashboard types
+
+There are two kinds of dashboards:
+
+* `mode = "exclude"`: The normal kind of dashboard.  Each rule
+  will filter the matching items from the board.
+* `mode = "include"`: Only items matching the rules are shown
+  on the board.
+
+```toml
+[main]
+mode = "include"
+```
+
+## Multiple Dashboards
+
+To have multiple dashboards, split the configuration into a main config in `config.toml` and create a folder containing the
+rule files for additional dashboards. These dashboards will appear in the navigation bar named like the corresponding files.
+
+
+### Example
+
+`tuwat -conf config.toml -dashboards tuwat.d`
+
+```toml
+# config.example.toml
+[[github]]
+Repos = ['synyx/tuwat', 'synyx/buchungsstreber']
+Tag = 'gh'
+```
+
+```toml
+# tuwat.d/no-drafts.toml
+[[rule]]
+description = "Ignore Drafts"
+[rule.label]
+Draft = "true"
+```
+
+```toml
+# tuwat.d/drafts.toml
+[main]
+mode = "include"
+
+[[rule]]
+description = "Show only drafts"
+[rule.label]
+Draft = "true"
+```

docs/rules.md

@@ -0,0 +1,69 @@
+# Rules
+
+The rule-system works via an exclude list, matching rules will include or
+exclude the matching items, depending on the
+[type of dashboard](dashboards.md#dashboard-types).
+
+The configuration is done via [toml](https://toml.io/).
+
+For example:
+
+```toml
+[[rule]]
+description = "blocked because not needed"
+what = "fooo service"
+```
+
+* The `description` field provides a visible explanation, why the item is
+  excluded.
+* The `what` field selects all items where the `What` matches the given
+  regular expression.
+
+```toml
+[[rule]]
+description = "Ignore Drafts"
+what = "Thing"
+when = "> 60"
+[rule.label]
+Draft = "true"
+```
+
+* The `label` section selects items via labels.  In this example it would match
+  an item which has the label `Draft` which matches the given regular expression.
+* The label rules will combine as `AND`.
+* `what` rules will combine as `AND` with label rules.
+* `when` rules will combine with `AND` with label and `what` rules.
+
+## Matching Rules
+
+The default is to match the value in the configuration as a regular expression.
+However, this can be changed by specifying an operator.
+
+* `~= string`: Explicitly require a regular expression to be matched.
+  This is the same as just leaving `~= ` out.
+* `=  string|number`: Require the string or number to exactly match.  In case  
+  the value is numeric, this will mean that the value will compared like a
+  floating point value.  This means that differences below `1e-8` will be
+  considered to be the same.
+* `>  number`: Require both configuration and the value in the alert to be a
+  numerical value and that the value in the alert to be bigger than the
+  configured number.
+  This also applies to the `<`, `>=`, `<=` operators.
+
+### Example
+
+```toml
+[[rule]]
+description = "Ignore certain group"
+[rule.label]
+groups = "= A-Group"
+
+[[rule]]
+description = "Ignore all with group beginning with A"
+[rule.label]
+groups = "~= (^|,)A"
+
+[[rule]]
+description = "Ignore old things"
+when = ">= 60"
+```