Feat/improve documentation on order of arguments

.pre-commit-config.yaml

@@ -19,7 +19,7 @@ repos:
       - id: golangci-lint-repo-mod
         args: [--config, .golangci.yaml, --, --fix]
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: v3.5.2
+    rev: v3.5.3
     hooks:
       - id: prettier
         files: \.(md|mdx)$

website/content/docs/0 - downscaler/0 - Arguments.mdx

@@ -24,7 +24,7 @@ The [Values](ref:docs-values) will be applied to the [cli layer](ref:docs-layers
 :::info
 
 `--explicit-include` will set the [exclude value](ref:docs-values#exclude) to `true` on the [cli layer](ref:docs-layers#cli-layer).
-This will exclude every workload unless [lower layers](ref:docs-layers) (e.g.: [namespace layer](ref:docs-layers#namespace-layer),
+This will exclude every workload unless [more specific layers](ref:docs-layers) (e.g.: [namespace layer](ref:docs-layers#namespace-layer),
 [workload layer](ref:docs-layers#workload-layer)) [specify](ref:docs-annotations) exclude to `false`.
 
 :::

website/content/docs/0 - downscaler/4 - Values.mdx

@@ -16,14 +16,46 @@ The default values shown below are only set on [the default layer](ref:docs-laye
 
 :::
 
+## Order
+
+Some of the values have a specific order in which they are evaluated.
+
+### Exclusion
+
+Exclusion contains all values which exclude the workload (e.g. [Exclude](#exclude), [Exclude Until](#exclude-until), [Grace Period](#grace-period)).
+
+These are ORed so if at least one of them excludes the workload, the workload will be excluded.
+
+### Scaling
+
+Scaling includes all values which influence the state of Scaling the workload should be in
+(e.g. [Force Downtime](#force-downtime), [Force Uptime](#force-uptime), [Downscale Period](#downscale-period),
+[Downtime](#downtime), [Upscale Period](#upscale-period), [Uptime](#uptime)).
+
+If [Force Downtime](#force-downtime) or [Force Uptime](#force-uptime) is
+true/[matching](ref:docs-timespans) during scaling their respective scaling will be used.
+Otherwise the [Downscale Period](#downscale-period), [Downtime](#downtime),
+[Upscale Period](#upscale-period) and [Uptime](#uptime) values are evaluated.
+
+:::note
+
+Currently if [Downscale Period](#downscale-period) and [Upscale Period](#upscale-period) is set,
+and both match the same time the workload will ignore scaling.
+This is _**NOT**_ final intended behavior and you should not rely on this.
+This will likely change in the future to be seen as an incompatibility.
+
+:::
+
 ## Downscale Period
 
 - Type: [Timespans](ref:docs-timespans)
 - Default: []
 - Within these periods the [workload](ref:docs-workload-types) will be scaled down.
-  Outside of the periods, scaling will be ignored.
+  Outside of the periods, scaling will be ignored/overwritten by [Upscale Period](#upscale-period).
 - Can be paired with [upscale period](#upscale-period)
 - Incompatible with [Downtime](#downtime) and [Uptime](#uptime)
+- [Grouped](ref:docs-layers#value-groups) with [downtime](#downtime),
+  [uptime](#uptime) and [upscale period](#upscale-period)
 
 ## Downtime
 
@@ -32,15 +64,19 @@ The default values shown below are only set on [the default layer](ref:docs-laye
 - Within these periods the [workload](ref:docs-workload-types) will be scaled down.
   Outside of the periods the [workload](ref:docs-workload-types) will be scaled up.
 - Incompatible with [downscale period](#downscale-period), [upscale period](#upscale-period) and [Uptime](#uptime)
+- [Grouped](ref:docs-layers#value-groups) with [downscale period](#downscale-period),
+  [uptime](#uptime) and [upscale period](#upscale-period)
 
 ## Upscale Period
 
 - Type: [Timespans](ref:docs-timespans)
 - Default: []
 - Within these periods the [workload](ref:docs-workload-types) will be scaled up.
-  Outside of the periods, scaling will be ignored.
+  Outside of the periods, scaling will be ignored/overwritten by [Downscale Period](#downscale-period).
 - Can be paired with [downscale period](#downscale-period)
 - Incompatible with [Downtime](#downtime) and [Uptime](#uptime)
+- [Grouped](ref:docs-layers#value-groups) with [downscale period](#downscale-period),
+  [uptime](#uptime) and [Downtime](#downtime)
 
 ## Uptime
 
@@ -49,10 +85,12 @@ The default values shown below are only set on [the default layer](ref:docs-laye
 - Within these periods the [workload](ref:docs-workload-types) will be scaled up.
   Outside of the periods the [workload](ref:docs-workload-types) will be scaled down.
 - Incompatible with [downscale period](#downscale-period), [upscale period](#upscale-period) and [Downtime](#downtime)
+- [Grouped](ref:docs-layers#value-groups) with [downscale period](#downscale-period),
+  [upscale period](#upscale-period) and [Downtime](#downtime)
 
 ## Exclude
 
-- Type: [Boolean](https://en.wikipedia.org/wiki/Boolean_data_type)
+- Type: [Timespans](ref:docs-timespans) (this also includes [true/false](ref:docs-timespans#alwaysnevertruefalse))
 - Default: false
 - Excludes the [workload](ref:docs-workload-types) from being scaled. (Scaling is ignored)
 
@@ -64,17 +102,19 @@ The default values shown below are only set on [the default layer](ref:docs-laye
 
 ## Force Uptime
 
-- Type: [Boolean](https://en.wikipedia.org/wiki/Boolean_data_type)
+- Type: [Timespans](ref:docs-timespans) (this also includes [true/false](ref:docs-timespans#alwaysnevertruefalse))
 - Default: false
 - Forces the [workload](ref:docs-workload-types) into an uptime state. (Scaling up)
 - Incompatible with [force downtime](#force-downtime)
+- [Grouped](ref:docs-layers#value-groups) with [force downtime](#force-downtime)
 
 ## Force Downtime
 
-- Type: [Boolean](https://en.wikipedia.org/wiki/Boolean_data_type)
+- Type: [Timespans](ref:docs-timespans) (this also includes [true/false](ref:docs-timespans#alwaysnevertruefalse))
 - Default: false
 - Forces the [workload](ref:docs-workload-types) into a downtime state. (Scaling down)
 - Incompatible with [force uptime](#force-uptime)
+- [Grouped](ref:docs-layers#value-groups) with [force uptime](#force-uptime)
 
 ## Downscale Replicas
 

website/content/docs/0 - downscaler/5 - Layers.mdx

@@ -11,13 +11,24 @@ They define a uniform way of how to select which of the values gets used.
 
 ## How It Works
 
-The resulting value is always the one set by the most specific layer.
+The resulting value is always the one set by the most specific layer that has set that value.
 
 This means [Workload Layer](#workload-layer) > [Namespace Layer](#namespace-layer) >
 [CLI Layer](#cli-layer) > [ENV Layer](#environment-layer) > [Default Layer](#default-layer).
 
 ![Layer Diagram](./assets/layer-diagram.png)
 
+### Value Groups
+
+Some [values](ref:docs-values) within one layer set/define very similar properties (e.g. [Force Downtime](ref:docs-values#force-downtime)
+and [Force Uptime](ref:docs-values#force-uptime); [Downscale Period](ref:docs-values#downscale-period),
+[Downtime](ref:docs-values#downtime), [Upscale Period](ref:docs-values#upscale-period) and [Uptime](ref:docs-values#uptime))
+
+These values are not all handled separately when choosing which layer to take the values from.
+Instead if one of them is set in a layer, the other values will be taken from the same layer.
+
+Incompatibilities between values normally only occur between values in the same value group and therefore the values on that same layer.
+
 ## Workload Layer
 
 Defined by the [annotations](ref:docs-values) on the [workload](ref:docs-workload-types) every scan.

website/content/docs/0 - downscaler/6 - types/0 - Timespans.mdx

@@ -8,10 +8,11 @@ globalReference: docs-timespans
 
 Timespans define periods of time.
 
-There are two types of timespans:
+There are three types of timespans:
 
 - [Absolute timespans](#absolute-timespans): a timespan defined by two absolute points in time
 - [Relative timespans](#relative-timespans): reoccurring on a weekly schedule
+- [Boolean timespans](#alwaysnevertruefalse): statically always or never active
 
 ## Absolute Timespans
 
@@ -70,6 +71,19 @@ but these (not including `UTC`) shouldn't be used, and only exist for backwards
 
 Values from: 00:00 - 24:00
 
+## Always/Never/True/False
+
+Case-insensitive:
+
+- Always/True: always matches
+- Never/False: never matches, acts as a [non-unset state](ref:docs-layers#how-it-works)
+
+:::tip
+
+Never/False and other non-unset states can be useful for disabling the value if set by less specific layers.
+
+:::
+
 ## Complex Timespans
 
 Sometimes its not enough to have just one timespan, in those cases you can define multiple.
@@ -81,4 +95,11 @@ Sometimes its not enough to have just one timespan, in those cases you can defin
   `Sat-Sun 00:00-24:00 Europe/Berlin, Mon-Fri 20:00-08:00 Europe/Berlin` -
   This expression matches the time over the weekend and at night.
 
-The you can mix any type of timespan.
+You can mix any type of timespan.
+
+:::note
+
+Although you could mix [boolean timespans](#alwaysnevertruefalse) with the other ones,
+this is not a valid use case and might be changed to a compatibility conflict in the future.
+
+:::

website/content/guides/2 - Migrating from py-kube-downscaler.mdx

@@ -93,6 +93,11 @@ See the [breaking changes entry](#stricter-exclusion) for more information.
 Configuration errors on workloads are now shown as error events on the workload.
 This makes it so you don't have to have access to the downscalers console just to see whats wrong with your configuration.
 
+### Booleans to Timespans
+
+All boolean [values](ref:docs-values) (e.g. force up/downtime, exclude)
+now support [timespans](ref:docs-timespans) to dynamically do things.
+
 ## Breaking Changes
 
 ### Incompatible Fields

website/plugins/global-ref-plugin.cts

@@ -3,7 +3,10 @@ import { visit } from "unist-util-visit";
 import { Node, Literal } from "unist";
 import { ParseFrontMatter } from "@docusaurus/types";
 
-const references: Map<string, { urlPath: string; title: string }> = new Map();
+const references: Map<
+  string,
+  { urlPath: string; title: string; file: string }
+> = new Map();
 
 export const globalRefParseFrontMatter: ParseFrontMatter = async ({
   defaultParseFrontMatter,
@@ -51,6 +54,7 @@ export const globalRefParseFrontMatter: ParseFrontMatter = async ({
   references.set(referenceId, {
     urlPath,
     title: result.frontMatter.title as string,
+    file: filePath,
   });
 
   return result;
@@ -65,6 +69,17 @@ export const docRefRemarkPlugin: Plugin = () => {
         (match, referenceId, headerId) => {
           const reference = references.get(referenceId);
 
+          if (file.path === reference.file) {
+            console.error(
+              `"%s:%d:%d": Reference '%s' called in own file`,
+              file.path,
+              node.position.start.line,
+              node.position.start.column,
+              referenceId
+            );
+            return match;
+          }
+
           // If the reference doesn't exist, log an error.
           if (!reference) {
             console.error(