[feat] docs; update admonition syntax (#68842)

* [feat] docs; update admonition syntax - Standardizes according to style conventions: https://grafana.com/docs/writers-toolkit/style-guide/style-conventions/#admonitions - Prepares docs for better, uniform admonition style. * Remove false positives and irregularities * false positive removal * Update docs/sources/datasources/mysql/_index.md * Update docs/sources/developers/angular_deprecation/angular-plugins.md * fix link errors * Prettify some nested blockquotes * remoe unnecessary admonition
2023-05-22 15:45:28 -05:00
parent c6c3a84349
commit 1c4bb9ca00
144 changed files with 1131 additions and 425 deletions
@@ -28,7 +28,9 @@ You can use variables in data links to refer to series fields, labels, and value

 To see a list of available variables, type `$` in the data link **URL** field to see a list of variables that you can use.

-> **Note:** These variables changed in 6.4 so if you have an older version of Grafana, then use the version picker to select docs for an older version of Grafana.
+{{% admonition type="note" %}}
+These variables changed in 6.4 so if you have an older version of Grafana, then use the version picker to select docs for an older version of Grafana.
+{{% /admonition %}}

 You can also use template variables in your data links URLs, refer to [Templates and variables]({{< relref "../../dashboards/variables/" >}}) for more information on template variables.

@@ -71,6 +71,8 @@ You can change legend mode to **Table** and choose [calculations]({{< relref "..

 The sort order affects the positions of the bars in the Bar chart panel as well as the order of stacked series in the Time series and Bar chart panels.

-> **Note:** This feature is only supported in these panels: Bar chart, Histogram, Time series, XY Chart.
+{{% admonition type="note" %}}
+This feature is only supported in these panels: Bar chart, Histogram, Time series, XY Chart.
+{{% /admonition %}}

 ![Sort legend series](/static/img/docs/legend/legend-series-sort-8-3.png).
@@ -86,7 +86,9 @@ Explore and export panel, panel data, and data frame JSON models.

 You can configure Grafana to dynamically add panels or rows to a dashboard. A dynamic panel is a panel that the system creates based on the value of a variable. Variables dynamically change your queries across all panels in a dashboard. For more information about repeating rows, refer to [Configure repeating rows](../add-organize-panels/#configure-repeating-rows).

-> **Note:** Repeating panels require variables to have one or more items selected; you cannot repeat a panel zero times to hide it.
+{{% admonition type="note" %}}
+Repeating panels require variables to have one or more items selected; you cannot repeat a panel zero times to hide it.
+{{% /admonition %}}

 To see an example of repeating panels, refer to [Prometheus dashboard with repeating panels](https://play.grafana.org/d/000000036/prometheus-repeat).

@@ -44,7 +44,9 @@ You can apply standard options to most built-in Grafana panels. Some older panel

 Most field options will not affect the visualization until you click outside of the field option box you are editing or press Enter.

-> **Note:** We are constantly working to add and expand options for all visualization, so all options might not be available for all visualizations.
+{{% admonition type="note" %}}
+We are constantly working to add and expand options for all visualization, so all options might not be available for all visualizations.
+{{% /admonition %}}

 ### Unit

@@ -24,7 +24,9 @@ Values mapped via value mappings bypass the unit formatting. This means that a t

 If value mappings are present in a panel, then Grafana displays a summary in the side pane of the panel editor.

-> **Note:** The new value mappings are not compatible with some visualizations, such as Graph (old), Text, and Heatmap.
+{{% admonition type="note" %}}
+The new value mappings are not compatible with some visualizations, such as Graph (old), Text, and Heatmap.
+{{% /admonition %}}

 ## Types of value mappings

@@ -63,7 +63,9 @@ The inspect drawer helps you understand and troubleshoot your panels. You can vi

 To access the panel inspect drawer from the edit view, hover over any part of the panel to display the actions menu on the top right corner. Click the menu and select **Inspect**.

-> **Note:** Not all panel types include all tabs. For example, dashboard list panels do not have raw data to inspect, so they do not display the Stats, Data, or Query tabs.
+{{% admonition type="note" %}}
+Not all panel types include all tabs. For example, dashboard list panels do not have raw data to inspect, so they do not display the Stats, Data, or Query tabs.
+{{% /admonition %}}

 The panel inspector consists of the following options:

@@ -21,11 +21,15 @@ Server-side expressions allow you to manipulate data returned from queries with

 Expressions are most commonly used for [Grafana Alerting]({{< relref "../../../alerting/" >}}). The processing is done server-side, so expressions can operate without a browser session. However, expressions can also be used with backend data sources and visualization.

-> **Note:** Expressions do not work with legacy dashboard alerts.
+{{% admonition type="note" %}}
+Expressions do not work with legacy dashboard alerts.
+{{% /admonition %}}

 Expressions are meant to augment data sources by enabling queries from different data sources to be combined or by providing operations unavailable in a data source.

-> **Note:** When possible, you should do data processing inside the data source. Copying data from storage to the Grafana server for processing is inefficient, so expressions are targeted at lightweight data processing.
+{{% admonition type="note" %}}
+When possible, you should do data processing inside the data source. Copying data from storage to the Grafana server for processing is inefficient, so expressions are targeted at lightweight data processing.
+{{% /admonition %}}

 Expressions work with data source queries that return time series or number data. They also operate on [multiple-dimensional data]({{< relref "../../../fundamentals/timeseries-dimensions/" >}}). For example, a query that returns multiple series, where each series is identified by labels or tags.

@@ -111,7 +115,9 @@ abs returns the absolute value of its argument which can be a number or a series

 is_inf takes a number or a series and returns `1` for `Inf` values (negative or positive) and `0` for other values. For example `is_inf($A)`.

-> **Note:** If you need to specifically check for negative infinity for example, you can do a comparison like `$A == infn()`.
+{{% admonition type="note" %}}
+If you need to specifically check for negative infinity for example, you can do a comparison like `$A == infn()`.
+{{% /admonition %}}

 ###### is_nan

@@ -200,7 +200,9 @@ In the example below, the panel has three queries (A, B, C). I removed the B que

 {{< figure src="/static/img/docs/transformations/filter-by-query-stat-example-7-0.png" class="docs-image--no-shadow" max-width= "1100px" >}}

-> **Note:** This transformation is not available for Graphite because this data source does not support correlating returned data with queries.
+{{% admonition type="note" %}}
+This transformation is not available for Graphite because this data source does not support correlating returned data with queries.
+{{% /admonition %}}

 ### Filter data by value

@@ -490,7 +492,9 @@ Here is the result after applying the Merge transformation.

 Use this transformation to rename, reorder, or hide fields returned by the query.

-> **Note:** This transformation only works in panels with a single query. If your panel has multiple queries, then you must either apply an Outer join transformation or remove the extra queries.
+{{% admonition type="note" %}}
+This transformation only works in panels with a single query. If your panel has multiple queries, then you must either apply an Outer join transformation or remove the extra queries.
+{{% /admonition %}}

 Grafana displays a list of fields returned by the query. You can:

@@ -661,7 +665,9 @@ As you can see each row in the source data becomes a separate field. Each field

 ### Prepare time series

-> **Note:** This transformation is available in Grafana 7.5.10+ and Grafana 8.0.6+.
+{{% admonition type="note" %}}
+This transformation is available in Grafana 7.5.10+ and Grafana 8.0.6+.
+{{% /admonition %}}

 Prepare time series transformation is useful when a data source returns time series data in a format that isn't supported by the panel you want to use. For more information about data frame formats, refer to [Data frames]({{< relref "../../../developers/plugins/data-frames/" >}}).

@@ -673,7 +679,9 @@ Select the `Wide time series` option to transform the time series data frame fro

 ### Series to rows

-> **Note:** This transformation is available in Grafana 7.1+.
+{{% admonition type="note" %}}
+This transformation is available in Grafana 7.1+.
+{{% /admonition %}}

 Use this transformation to combine the result from multiple time series data queries into one single result. This is helpful when using the table panel visualization.

@@ -737,6 +745,8 @@ Here is the result after adding a Limit transformation with a value of '3':

 ### Time series to table transform

-> **Note:** This transformation is available in Grafana 9.5+ as an opt-in beta feature. Modify Grafana [configuration file]({{< relref "../../../setup-grafana/configure-grafana/#configuration-file-location" >}}) to enable the `timeSeriesTable` [feature toggle]({{< relref "../../../setup-grafana/configure-grafana/#feature_toggles" >}}) to use it.
+{{% admonition type="note" %}}
+This transformation is available in Grafana 9.5+ as an opt-in beta feature. Modify Grafana [configuration file]({{< relref "../../../setup-grafana/configure-grafana/#configuration-file-location" >}}) to enable the `timeSeriesTable` [feature toggle]({{< relref "../../../setup-grafana/configure-grafana/#feature_toggles" >}}) to use it.
+{{% /admonition %}}

 Use this transformation to convert time series result into a table, converting time series data frame into a "Trend" field. "Trend" field can then be rendered using [sparkline cell type]({{< relref "../../visualizations/table/#sparkline" >}}), producing an inline sparkline for each table row. If there are multiple time series queries, each will result in a separate table data frame. These can be joined using join or merge transforms to produce a single table with multiple sparklines per row.
@@ -14,7 +14,9 @@ weight: 75

 Grafana offers a variety of visualizations to support different use cases. This section of the documentation highlights the built-in panels, their options and typical usage.

-> **Note:** If you are unsure which visualization to pick, Grafana can provide visualization suggestions based on the panel query. When you select a visualization, Grafana will show a preview with that visualization applied.
+{{% admonition type="note" %}}
+If you are unsure which visualization to pick, Grafana can provide visualization suggestions based on the panel query. When you select a visualization, Grafana will show a preview with that visualization applied.
+{{% /admonition %}}

 - Graphs & charts
  - [Time series]({{< relref "time-series/" >}}) is the default and main Graph visualization.
@@ -39,7 +39,9 @@ Use the time range option to specify whether the list should be limited to the c

 Use the tags option to filter the annotations by tags. You can add multiple tags in order to refine the list.

-> **Note:** Optionally, leave the tag list empty and filter on the fly by selecting tags that are listed as part of the results on the panel itself.
+{{% admonition type="note" %}}
+Optionally, leave the tag list empty and filter on the fly by selecting tags that are listed as part of the results on the panel itself.
+{{% /admonition %}}

 ### Limit

@@ -48,7 +48,9 @@ The **Up color** and **Down color** options select which colors are used when th

 The candlestick panel will attempt to map fields to the appropriate dimension. The **Open**, **High**, **Low**, and **Close** options allow you to map your data to these dimensions if the panel is unable to do so.

-> **Note**: These values are hidden from the legend.
+{{% admonition type="note" %}}
+These values are hidden from the legend.
+{{% /admonition %}}

 - **Open** corresponds to the starting value of the given period.
 - **High** corresponds to the highest value of the given period.
@@ -90,7 +90,9 @@ There are also five alpha layer types.
 - [Route layer (Alpha)]({{< relref "#route-layer-alpha" >}}) render data points as a route.
 - [Photos layer (Alpha)]({{< relref "#photos-layer-alpha" >}}) renders a photo at each data point.

-> **Note:** [Basemap layer types]({{< relref "#types-1" >}}) can also be added as layers. You can specify an opacity.
+{{% admonition type="note" %}}
+[Basemap layer types]({{< relref "#types-1" >}}) can also be added as layers. You can specify an opacity.
+{{% /admonition %}}

 ### Layer Controls

@@ -433,7 +435,9 @@ Displays scale information in the bottom left corner.

 {{< figure src="/static/img/docs/geomap-panel/geomap-map-controls-scale-9-1-0.png" max-width="1200px" caption="Geomap panel scale" >}}

-> **Note:** Currently only displays units in [m]/[km].
+{{% admonition type="note" %}}
+Currently only displays units in [m]/[km].
+{{% /admonition %}}

 ### Show measure tools

@@ -445,7 +449,9 @@ Displays measure tools in the upper right corner. Measurements appear only when
 - **Continue clicking** to continue measurement
 - **Double-click** to end measurement

-> **Note:** <br /> - When you change measurement type or units, the previous measurement is removed from the map. <br /> - If the control is closed and then re-opened, the most recent measurement is displayed. <br /> - A measurement can be modified by clicking and dragging on it.
+{{% admonition type="note" %}}
+<br /- When you change measurement type or units, the previous measurement is removed from the map. <br /- If the control is closed and then re-opened, the most recent measurement is displayed. <br /- A measurement can be modified by clicking and dragging on it.
+{{% /admonition %}}

 #### Length

@@ -32,7 +32,9 @@ Both nodes and edges can have associated metadata or statistics. The data source

 ### Nodes

-> **Note:** Node graph can show only 1,500 nodes. If this limit is crossed a warning will be visible in upper right corner, and some nodes will be hidden. You can expand hidden parts of the graph by clicking on the "Hidden nodes" markers in the graph.
+{{% admonition type="note" %}}
+Node graph can show only 1,500 nodes. If this limit is crossed a warning will be visible in upper right corner, and some nodes will be hidden. You can expand hidden parts of the graph by clicking on the "Hidden nodes" markers in the graph.
+{{% /admonition %}}

 Usually, nodes show two statistical values inside the node and two identifiers just below the node, usually name and type. Nodes can also show another set of values as a color circle around the node, with sections of different color represents different values that should add up to 1.

@@ -20,7 +20,9 @@ The Stat panel visualization shows a one large stat value with an optional graph

 {{< figure src="/static/img/docs/v66/stat_panel_dark3.png" max-width="1025px" caption="Stat panel" >}}

-> **Note:** This panel replaces the Singlestat panel, which was deprecated in Grafana 7.0 and removed in Grafana 8.0.
+{{% admonition type="note" %}}
+This panel replaces the Singlestat panel, which was deprecated in Grafana 7.0 and removed in Grafana 8.0.
+{{% /admonition %}}

 By default, the Stat panel displays one of the following:

@@ -39,7 +39,9 @@ Click a column title to change the sort order from default to descending to asce

 ## Table options

-> **Note:** If you are using a table visualization created before Grafana 7.0, then you need to migrate to the new table version in order to see these options. To migrate, on the Panel tab, click **Table** visualization. Grafana updates the table version and you can then access all table options.
+{{% admonition type="note" %}}
+If you are using a table visualization created before Grafana 7.0, then you need to migrate to the new table version in order to see these options. To migrate, on the Panel tab, click **Table** visualization. Grafana updates the table version and you can then access all table options.
+{{% /admonition %}}

 ### Show header

@@ -72,7 +74,9 @@ Choose how Grafana should align cell contents:

 By default, Grafana automatically chooses display settings. You can override the settings by choosing one of the following options to set the default for all fields. Additional configuration is available for some cell types.

-> **Note:** If you set these in the Field tab, then the type will apply to all fields, including the time field. Many options will work best if you set them in the Override tab so that they can be restricted to one or more fields.
+{{% admonition type="note" %}}
+If you set these in the Field tab, then the type will apply to all fields, including the time field. Many options will work best if you set them in the Override tab so that they can be restricted to one or more fields.
+{{% /admonition %}}

 ### Color text

@@ -140,7 +144,9 @@ If you have a field value that is an image URL or a base64 encoded image you can

 ### Sparkline

-> **Note:** This cell type is available in Grafana 9.5+ as an opt-in beta feature. Modify Grafana [configuration file]({{< relref "../../../setup-grafana/configure-grafana/#configuration-file-location" >}}) to enable the `timeSeriesTable` [feature toggle]({{< relref "../../../setup-grafana/configure-grafana/#feature_toggles" >}}) to use it.
+{{% admonition type="note" %}}
+This cell type is available in Grafana 9.5+ as an opt-in beta feature. Modify Grafana [configuration file]({{< relref "../../../setup-grafana/configure-grafana/#configuration-file-location" >}}) to enable the `timeSeriesTable` [feature toggle]({{< relref "../../../setup-grafana/configure-grafana/#feature_toggles" >}}) to use it.
+{{% /admonition %}}

 Shows value rendered as a sparkline. Requires [time series to table]({{< relref "../../query-transform-data/transform-data/#time-series-to-table-transform" >}}) data transform.

@@ -150,7 +156,9 @@ Shows value rendered as a sparkline. Requires [time series to table]({{< relref

 Enables value inspection from table cell. The raw value is presented in a modal window.

-> **Note:** Cell value inspection is only available when cell display mode is set to Auto, Color text, Color background or JSON View.
+{{% admonition type="note" %}}
+Cell value inspection is only available when cell display mode is set to Auto, Color text, Color background or JSON View.
+{{% /admonition %}}

 ## Column filter

@@ -34,7 +34,9 @@ weight: 90

 The time series visualization type is the default and primary way to visualize time series data as a graph. It can render series as lines, points, or bars. It is versatile enough to display almost any time-series data. [This public demo dashboard](https://play.grafana.org/d/000000016/1-time-series-graphs?orgId=1) contains many different examples of how it can be configured and styled.

-> **Note:** You can migrate from the old Graph visualization to the new Time series visualization. To migrate, open the panel and click the **Migrate** button in the side pane.
+{{% admonition type="note" %}}
+You can migrate from the old Graph visualization to the new Time series visualization. To migrate, open the panel and click the **Migrate** button in the side pane.
+{{% /admonition %}}

 ## Tooltip options

@@ -222,7 +224,9 @@ Use this option to transform the series values without affecting the values show
 - **Negative Y transform:** Flip the results to negative values on the Y axis.
 - **Constant:** Show the first value as a constant line.

-> **Note:** The transform option is only available as an override.
+{{% admonition type="note" %}}
+The transform option is only available as an override.
+{{% /admonition %}}

 ## Color options

@@ -13,7 +13,9 @@ weight: 850

 # Traces panel

-> **Note:** This panel is currently in beta. Expect changes in future releases.
+{{% admonition type="note" %}}
+This panel is currently in beta. Expect changes in future releases.
+{{% /admonition %}}

 _Traces_ are a visualization that enables you to track and log a request as it traverses the services in your infrastructure.