Initial commit for adding available_time_ranges to docs (#3578)

docs/docs/reference/project-files/dashboards.md

@@ -14,7 +14,7 @@ _**`title`**_ — the display name for the dashboard _(required)_
 
 _**`timeseries`**_ — the timestamp column from your model that will underlie x-axis data in the line charts _(optional)_. If not specified, the line charts will not appear.
 
-_**`default_time_range`**_ — the default time range shown when a user initially loads the dashboard _(optional)_. The value must be either a valid [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) (for example, `PT12H` for 12 hours, `P1M` for 1 month, or `P26W` for 26 weeks) or the constant value `inf` for all time (default). If not specified, defaults to the full time range of the `timeseries` column.
+_**`default_time_range`**_ — the default time range shown when a user initially loads the dashboard _(optional)_. The value must be either a valid [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) (for example, `PT12H` for 12 hours, `P1M` for 1 month, or `P26W` for 26 weeks) or one of the [Rill ISO 8601 extensions](../rill-iso-extensions.md#extensions) (default). If not specified, defaults to the full time range of the `timeseries` column.
 
 _**`smallest_time_grain`**_ — the smallest time granularity the user is allowed to view in the dashboard _(optional)_. The valid values are: `millisecond`, `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`.
 
@@ -49,6 +49,25 @@ _**`measures`**_ — numeric [aggregates](../../develop/metrics-dashboard#measur
     - _`percentage`_ — output transformed from a rate to a percentage appended with a percentage sign
     - _`interval_ms`_ — time intervals given in milliseconds are transformed into human readable time units like hours (h), days (d), years (y), etc
 
+_**`available_time_ranges`**_ — Override the list of default time range selections available in the dropdown _(optional)_. Note that `All Time` and `Custom` selections are always available.
+  - _**`range`**_ — a valid [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) or one of the [Rill ISO 8601 extensions](../rill-iso-extensions.md#extensions) for the selection _(required)_
+  - _**`comparison_offsets`**_ — list of time comparison options for this time range selection _(optional)_. Must be one of the [Rill ISO 8601 extensions](../rill-iso-extensions.md#extensions).
+  - **Example**:
+    ```yaml
+    available_time_ranges:
+    - PT15M // Simplified syntax to specify only the range
+    - PT1H
+    - PT6H
+    - P7D
+    - range: P5D // Advanced syntax to specify comparison_offsets as well
+      comparison_offsets:
+        - rill-PP
+        - rill-PW
+    - P4W
+    - rill-TD // Today
+    - rill-WTD // Week-To-date
+    ```
+
 _**`security`**_ - define a [security policy](../../develop/security) for the dashboard _(optional)_
   - _**`access`**_ - Expression indicating if the user should be granted access to the dashboard. If not defined, it will resolve to `false` and the dashboard won't be accessible to anyone. Needs to be a valid SQL expression that evaluates to a boolean. _(optional)_
   - _**`row_filter`**_ - SQL expression to filter the underlying model by. Can leverage templated user attributes to customize the filter for the requesting user. Needs to be a valid SQL expression that can be injected into a `WHERE` clause. _(optional)_

docs/docs/reference/rill-iso-extensions.md

@@ -0,0 +1,27 @@
+---
+title: Rill extensions to ISO 8601
+description: All the extensions options to the standard ISO 8601 duration standard
+sidebar_label: Rill extensions to ISO 8601
+sidebar_position: 13
+---
+
+We have extended the ISO 8601 standard to specify ranges like `Week-to-Date`.
+
+### Extensions
+
+| Rill ISO extension | Description      | As Time Range | As Time Comparison |
+|--------------------|------------------|---------------|--------------------|
+| inf                | All time         | Yes           | No                 |
+| rill-TD            | Today            | Yes           | No                 |
+| rill-WTD           | Week to Date     | Yes           | No                 |
+| rill-MTD           | Month to Date    | Yes           | No                 |
+| rill-QTD           | Quarter to Date  | Yes           | No                 |
+| rill-YTD           | Year to Date     | Yes           | No                 |
+| rill-YTD           | Year to Date     | Yes           | No                 |
+| rill-PP            | Last Period      | No            | Yes                |
+| rill-PD            | Previous Day     | No            | Yes                |
+| rill-PW            | Previous Week    | No            | Yes                |
+| rill-PM            | Previous Month   | No            | Yes                |
+| rill-PQ            | Previous Quarter | No            | Yes                |
+| rill-PY            | Previous Year    | No            | Yes                |
+