From 15f7502c7e8dbeaa56603241e8ace865cf7bb9ec Mon Sep 17 00:00:00 2001
From: Jochem van Dooren <jochemvandooren@hotmail.nl>
Date: Mon, 27 May 2024 17:42:03 +0200
Subject: [PATCH] Add configuration documentation

---
 docs/configuration.md | 66 +++++++++++++++++++++++++++++++++++++++++++
 docs/create_rules.md  | 23 +++++++++++++++
 mkdocs.yml            |  1 +
 3 files changed, 90 insertions(+)
 create mode 100644 docs/configuration.md

diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..422037f
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,66 @@
+# Configuration
+
+`dbt-score` can be configured through a `pyproject.toml` file or via the command
+line.
+
+## pyproject.toml
+
+It is recommended to place the file in the root of your dbt project. `dbt-score`
+will look for `pyproject.toml` in the directory from which it is run and it's
+parent directories.
+
+An example of a `pyproject.toml` file to configure `dbt-score` can be found
+below:
+
+```toml
+[tool.dbt-score]
+rule_namespaces = ["dbt_score.rules", "custom_rules"]
+disabled_rules = ["dbt_score.rules.generic.columns_have_description"]
+
+[tool.dbt-score.rules."dbt_score.rules.generic.sql_has_reasonable_size"]
+severity = 1
+max_lines = 300
+```
+
+### Configuration options
+
+The following options can be set in the `pyproject.toml` file:
+
+#### Main configuration
+
+```toml
+[tool.dbt-score]
+```
+
+- `rule_namespaces`: A list of namespaces to search for rules. The default is
+  `["dbt_score.rules", "dbt_score_rules"]`. Be aware when overriding this
+  setting, that the default rules are in `dbt_score.rules` and are disabled if
+  not included here.
+- `disabled_rules`: A list of rules to disable.
+
+#### Rule configuration
+
+```toml
+[tool.dbt-score.rules."rule_namespace.rule_name"]
+```
+
+Every rule can be configured with the following option:
+
+- `severity`: The severity of the rule. An integer with a minimum value of 1 and
+  a maximum value of 4.
+
+Some rules have additional configuration options, e.g.
+[sql_has_reasonable_size](/rules/generic/#sql_has_reasonable_size). Depending on
+the rule, the options will have different names, types and default values. In
+the case of the
+[sql_has_reasonable_size](/rules/generic/#sql_has_reasonable_size), the
+`max_lines` option can be configured.
+
+## Command line
+
+All configuration options can also be set via the command line. To understand
+how to configure `dbt-score` from the command line:
+
+```bash
+dbt score lint --help
+```
diff --git a/docs/create_rules.md b/docs/create_rules.md
index 26eabe3..15f9ab2 100644
--- a/docs/create_rules.md
+++ b/docs/create_rules.md
@@ -69,3 +69,26 @@ rules defined in `.py` files will be automatically discovered.
 If nested folders are used, e.g. `dbt_score_rules/generic_rules/rules.py`, an
 `__init__.py` file needs to be present in the nested folder to make it
 discoverable.
+
+### Configurable rules
+
+It's possible to create rules that can be
+[configured](configuration.md/#tooldbt-scorerulesrule_namespacerule_name) with
+additional options (apart from the `severity`). In order to create a
+configurable rule, the evaluation function of the rule should have additional
+input parameters with a default value defined. In the example below, the rule
+has a `max_lines` parameter with a default value of 200, which can be configured
+in the `pyproject.toml` file.
+
+```python
+from dbt_score import Model, rule, RuleViolation
+
+@rule
+def sql_has_reasonable_size(model: Model, max_lines: int = 200) -> RuleViolation | None:
+    """The SQL query of a model should not be too long."""
+    count_lines = len(model.raw_code.split("\n"))
+    if count_lines > max_lines:
+        return RuleViolation(
+            message=f"SQL query too long: {count_lines} lines (> {max_lines})."
+        )
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index 84ea25b..bc8fe09 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -19,6 +19,7 @@ nav:
   - Home: index.md
   - Get started: get_started.md
   - Create rules: create_rules.md
+  - Configuration: configuration.md
   - Rules:
       - rules/generic.md
   - Reference: