From 258b8b6e147be5d311de78c45bb7a63482236ef8 Mon Sep 17 00:00:00 2001
From: Anders Eknert <anders@styra.com>
Date: Thu, 10 Aug 2023 11:10:20 +0200
Subject: [PATCH] Move "Exceptions" to after "Rationale" (#245)

IMHO it makes sense to first present *why*, then the cases for when
exceptions might make sense.

Also made H2's for these sections.

Signed-off-by: Anders Eknert <anders@styra.com>
---
 docs/rules/imports/avoid-importing-input.md   | 12 ++++++------
 docs/rules/style/avoid-get-and-list-prefix.md | 12 ++++++------
 docs/rules/style/prefer-snake-case.md         | 14 +++++++-------
 3 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/docs/rules/imports/avoid-importing-input.md b/docs/rules/imports/avoid-importing-input.md
index 61d0314a..91d2e548 100644
--- a/docs/rules/imports/avoid-importing-input.md
+++ b/docs/rules/imports/avoid-importing-input.md
@@ -35,7 +35,11 @@ allow if {
 }
 ```
 
-**Exceptions**
+## Rationale
+
+Using an import for `input` is not necessary, as both `input` and `data` are globally available.
+
+## Exceptions
 
 Using an alias for `input` can sometimes be useful, e.g. when using `input` is known to represent something specific,
 like a Terraform plan. Aliasing of specific input attributes should however be avoided in favor of local assignments.
@@ -58,16 +62,12 @@ allow if {
 }
 ```
 
-## Rationale
-
-Using an import for `input` is not necessary, as both `input` and `data` are globally available. 
-
 ## Configuration Options
 
 This linter rule provides the following configuration options:
 
 ```yaml
-rules: 
+rules:
   imports:
     avoid-importing-input:
       # one of "error", "warning", "ignore"
diff --git a/docs/rules/style/avoid-get-and-list-prefix.md b/docs/rules/style/avoid-get-and-list-prefix.md
index e193551b..9c62ceec 100644
--- a/docs/rules/style/avoid-get-and-list-prefix.md
+++ b/docs/rules/style/avoid-get-and-list-prefix.md
@@ -31,11 +31,6 @@ developers contains user if {
 }
 ```
 
-**Exceptions**
-
-Using `is_`, or `has_` for boolean helper functions, like `is_admin(user)` may be easier to comprehend than
-`admin(user)`.
-
 ## Rationale
 
 Since Rego evaluation is generally free of side effects, any rule or function is essentially a "getter". Adding a
@@ -43,12 +38,17 @@ Since Rego evaluation is generally free of side effects, any rule or function is
 `resources`. Additionally, the type and return value of the rule should serve to tell whether a rule might return a
 single value (i.e. a complete rule) or a collection (a partial rule).
 
+## Exceptions
+
+Using `is_`, or `has_` for boolean helper functions, like `is_admin(user)` may be easier to comprehend than
+`admin(user)`.
+
 ## Configuration Options
 
 This linter rule provides the following configuration options:
 
 ```yaml
-rules: 
+rules:
   style:
     avoid-get-and-list-prefix:
       # one of "error", "warning", "ignore"
diff --git a/docs/rules/style/prefer-snake-case.md b/docs/rules/style/prefer-snake-case.md
index 6daf951b..baed1447 100644
--- a/docs/rules/style/prefer-snake-case.md
+++ b/docs/rules/style/prefer-snake-case.md
@@ -26,24 +26,24 @@ import future.keywords.in
 user_is_admin if "admin" in input.user.roles
 ```
 
-**Exceptions**
+## Rationale
+
+The built-in functions use `snake_case` for naming — follow that convention for your own rules, functions, and
+variables, unless you have a really good reason not to.
+
+## Exceptions
 
 In many cases, you might not control the format of the `input` data — if the domain of a policy (e.g. Envoy)
 mandates a different style, making an exception might seem reasonable. Adapting policy format after `input` is however
 prone to inconsistencies, as you'll likely end up mixing different styles in the same policy (due to imports of common
 code, etc).
 
-## Rationale
-
-The built-in functions use `snake_case` for naming — follow that convention for your own rules, functions, and
-variables, unless you have a really good reason not to.
-
 ## Configuration Options
 
 This linter rule provides the following configuration options:
 
 ```yaml
-rules: 
+rules:
   style:
     prefer-snake-case:
       # one of "error", "warning", "ignore"