Try to improve documentation for new users (#9952)

* Try to improve documentation for new users
* Review update

Author: kurkle

docs/configuration/index.md

@@ -2,6 +2,38 @@
 
 The configuration is used to change how the chart behaves. There are properties to control styling, fonts, the legend, etc.
 
+## Cofiguration object structure
+
+The top level structure of Chart.js configuration:
+
+```javascript
+const config = {
+  type: 'line'
+  data: {}
+  options: {}
+  plugins: []
+}
+```
+
+### type
+
+Chart type determines the main type of the chart.
+
+**note** A dataset can override the `type`, this is how mixed charts are constructed.
+
+### data
+
+See [Data Structures](../general/data-structures) for details.
+
+### options
+
+Majority of the documentation talks about these options.
+
+### plugins
+
+Inline plugins can be included in this array. It is an alternative way of adding plugins for single chart (vs registering the plugin globally).
+More about plugins in the [developers section](../developers/plugins.md).
+
 ## Global Configuration
 
 This concept was introduced in Chart.js 1.0 to keep configuration [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself), and allow for changing options globally across chart types, avoiding the need to specify options for each instance, or the default for a particular chart type.

docs/configuration/interactions.md

@@ -108,6 +108,8 @@ When configuring the interaction with the graph via `interaction`, `hover` or `t
 
 The modes are detailed below and how they behave in conjunction with the `intersect` setting.
 
+See how different modes work with the tooltip in [tooltip interactions sample](../samples/tooltip/interactions.md )
+
 ### point
 
 Finds all of the items that intersect the point.
@@ -126,7 +128,7 @@ const chart = new Chart(ctx, {
 
 ### nearest
 
-Gets the items that are at the nearest distance to the point. The nearest item is determined based on the distance to the center of the chart item (point, bar). You can use the `axis` setting to define which directions are used in distance calculation. If `intersect` is true, this is only triggered when the mouse position intersects an item in the graph. This is very useful for combo charts where points are hidden behind bars.
+Gets the items that are at the nearest distance to the point. The nearest item is determined based on the distance to the center of the chart item (point, bar). You can use the `axis` setting to define which coordinates are considered in distance calculation. If `intersect` is true, this is only triggered when the mouse position intersects an item in the graph. This is very useful for combo charts where points are hidden behind bars.
 
 ```javascript
 const chart = new Chart(ctx, {

docs/general/data-structures.md

@@ -8,24 +8,44 @@ The provides labels can be of the type string or number to be rendered correctly
 ## Primitive[]
 
 ```javascript
-data: [20, 10],
-labels: ['a', 'b']
+type: 'bar',
+data: {
+    datasets: [{
+      data: [20, 10],
+    }],
+    labels: ['a', 'b']
+}
 ```
 
 When the `data` is an array of numbers, values from `labels` array at the same index are used for the index axis (`x` for vertical, `y` for horizontal charts).
 
 ## Object[]
 
 ```javascript
-data: [{x: 10, y: 20}, {x: 15, y: null}, {x: 20, y: 10}]
+type: 'line',
+data: {
+  datasets: [{
+    data: [{x: 10, y: 20}, {x: 15, y: null}, {x: 20, y: 10}]
+  }]
+}
 ```
 
 ```javascript
-data: [{x:'2016-12-25', y:20}, {x:'2016-12-26', y:10}]
+type: 'line',
+data: {
+  datasets: [{
+    data: [{x:'2016-12-25', y:20}, {x:'2016-12-26', y:10}]
+  }]
+}
 ```
 
 ```javascript
-data: [{x:'Sales', y:20}, {x:'Revenue', y:10}]
+type: 'bar',
+data: {
+  datasets: [{
+    data: [{x:'Sales', y:20}, {x:'Revenue', y:10}]
+  }]
+}
 ```
 
 This is also the internal format used for parsed data. In this mode, parsing can be disabled by specifying `parsing: false` at chart options or dataset. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally.
@@ -68,9 +88,14 @@ options: {
 ## Object
 
 ```javascript
+type: 'pie',
 data: {
-    January: 10,
-    February: 20
+    datasets: [{
+      data: {
+          January: 10,
+          February: 20
+      }
+    }]
 }
 ```
 

docs/getting-started/index.md

@@ -18,6 +18,50 @@ Now that we have a canvas we can use, we need to include Chart.js in our page.
 
 Now, we can create a chart. We add a script to our page:
 
+```html
+<script>
+  const labels = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+  ];
+
+  const data = {
+    labels: labels,
+    datasets: [{
+      label: 'My First dataset',
+      backgroundColor: 'rgb(255, 99, 132)',
+      borderColor: 'rgb(255, 99, 132)',
+      data: [0, 10, 5, 2, 20, 30, 45],
+    }]
+  };
+
+  const config = {
+    type: 'line',
+    data: data,
+    options: {}
+  };
+</script>
+```
+
+Finally, render the chart using our configuration:
+
+```html
+<script>
+  const myChart = new Chart(
+    document.getElementById('myChart'),
+    config
+  );
+</script>
+```
+
+It's that easy to get started using Chart.js! From here you can explore the many options that can help you customise your charts with scales, tooltips, labels, colors, custom actions, and much more.
+
+Here the sample above is presented with our sample block:
+
 ```js chart-editor
 // <block:setup:1>
 const labels = [
@@ -53,21 +97,10 @@ module.exports = {
 };
 ```
 
-Finally, render the chart using our configuration:
-
-```html
-<script>
-  // === include 'setup' then 'config' above ===
-
-  const myChart = new Chart(
-    document.getElementById('myChart'),
-    config
-  );
-</script>
-```
-
-It's that easy to get started using Chart.js! From here you can explore the many options that can help you customise your charts with scales, tooltips, labels, colors, custom actions, and much more.
+:::tip Note
+As you can see, some of the boilerplate needed is not visible in our sample blocks, as the samples focus on the configuration options.
+:::
 
-All our examples are [available online](/samples/) but you can also download the `Chart.js.zip` archive attached to every [release](https://github.com/chartjs/Chart.js/releases) to experiment with our samples locally from the `/samples` folder.
+All our examples are [available online](/samples/).
 
 To run the samples locally you first have to install all the necessary packages using the `npm ci` command, after this you can run `npm run docs:dev` to build the documentation. As soon as the build is done, you can go to [http://localhost:8080/samples/](http://localhost:8080/samples/) to see the samples.

docs/samples/tooltip/interactions.md

@@ -30,13 +30,29 @@ const actions = [
     }
   },
   {
-    name: 'Mode: nearest',
+    name: 'Mode: nearest, axis: xy',
     handler(chart) {
       chart.options.interaction.axis = 'xy';
       chart.options.interaction.mode = 'nearest';
       chart.update();
     }
   },
+  {
+    name: 'Mode: nearest, axis: x',
+    handler(chart) {
+      chart.options.interaction.axis = 'x';
+      chart.options.interaction.mode = 'nearest';
+      chart.update();
+    }
+  },
+  {
+    name: 'Mode: nearest, axis: y',
+    handler(chart) {
+      chart.options.interaction.axis = 'y';
+      chart.options.interaction.mode = 'nearest';
+      chart.update();
+    }
+  },
   {
     name: 'Mode: x',
     handler(chart) {
@@ -98,8 +114,8 @@ const config = {
       title: {
         display: true,
         text: (ctx) => {
-          const {intersect, mode} = ctx.chart.options.interaction;
-          return 'Mode: ' + mode + ', intersect: ' + intersect;
+          const {axis = 'xy', intersect, mode} = ctx.chart.options.interaction;
+          return 'Mode: ' + mode + ', axis: ' + axis + ', intersect: ' + intersect;
         }
       },
     }
@@ -111,4 +127,4 @@ module.exports = {
   actions: actions,
   config: config,
 };
-```
+```