Rewrite Matplotlib integration page (#628)

docs/guides/frameworks/matplotlib/matplotlib_example.md

@@ -1,6 +1,5 @@
 ---
 title: Matplotlib
-displayed_sidebar: mainSidebar
 ---
 
 The example below demonstrates integrating ClearML into code that uses `matplotlib` to plot scatter diagrams, and 
@@ -23,18 +22,18 @@ which is associated with the `examples` project (in script) or the `Colab notebo
 
 The scatter plots appear in the **ClearML Web UI**, in **PLOTS**.
 
-![image](../../../img/examples_matplotlib_example_01.png)
+![Matplotlib plot 1](../../../img/examples_matplotlib_example_01.png)
 
-![image](../../../img/examples_matplotlib_example_02.png)
+![Matplotlib plot 2](../../../img/examples_matplotlib_example_02.png)
 
-![image](../../../img/examples_matplotlib_example_03.png)
+![Matplotlib plot 3](../../../img/examples_matplotlib_example_03.png)
 
 ## Debug Samples
 
 The images appear in **DEBUG SAMPLES**. Each debug sample image is associated with a metric.
 
-![image](../../../img/examples_matplotlib_example_04.png)
+![Matplotlib image plot](../../../img/examples_matplotlib_example_04.png)
 
 View the debug sample in the image viewer.
 
-![image](../../../img/examples_matplotlib_example_05.png)
+![Image viewer](../../../img/examples_matplotlib_example_05.png)

docs/integrations/matplotlib.md

@@ -0,0 +1,72 @@
+---
+title: Matplotlib
+---
+
+:::tip
+If you are not already using ClearML, see [Getting Started](../getting_started/ds/ds_first_steps.md) for setup 
+instructions.
+:::
+
+[Matplotlib](https://matplotlib.org/) is a Python library for data visualization. ClearML automatically captures plots 
+and images created with `matplotlib`. 
+
+All you have to do is add two lines of code to your script:
+
+```python
+from clearml import Task
+
+task = Task.init(task_name="<task_name>", project_name="<project_name>")
+```
+
+This will create a ClearML Task that captures your script's information, including Git details, uncommitted code, python 
+environment, your matplotlib visualizations, and more. View these matplotlib plots and images in the [WebApp](../webapp/webapp_exp_track_visual.md), 
+in the experiment's **Plots** and **Debug Samples** tabs respectively.
+
+![image](../img/examples_matplotlib_example_01.png)
+
+## Automatic Logging Control 
+By default, when ClearML is integrated into your script, it captures all of your matplotlib visualizations. 
+But, you may want to have more control over what your experiment logs.
+
+To control a task's framework logging, use the `auto_connect_frameworks` parameter of [`Task.init()`](../references/sdk/task.md#taskinit). 
+Completely disable all automatic logging by setting the parameter to `False`. For finer grained control of logged 
+frameworks, input a dictionary, with framework-boolean pairs.
+
+For example:
+
+```python
+auto_connect_frameworks={
+   'matplotlib': False, 'tensorflow': False, 'tensorboard': False, 'pytorch': True,
+   'xgboost': False, 'scikit': True, 'fastai': True, 'lightgbm': False,
+   'hydra': True, 'detect_repository': True, 'tfdefines': True, 'joblib': True,
+   'megengine': True, 'jsonargparse': True, 'catboost': True
+}
+```
+
+## Manual Logging
+To augment its automatic logging, ClearML also provides an explicit logging interface.
+
+Use [`Logger.report_matplotlib_figure()`](../references/sdk/logger.md#report_matplotlib_figure) to explicitly log 
+a matplotlib figure, and specify its title and series names, and iteration number:
+
+
+```
+logger = task.get_logger()
+
+area = (40 * np.random.rand(N))**2
+plt.scatter(x, y, s=area, c=colors, alpha=0.5)
+logger.report_matplotlib_figure(title="My Plot Title", series="My Plot Series", iteration=10, figure=plt)
+plt.show()
+```
+
+The logged figure is displayed in the experiment's **Plots** tab. 
+
+![Experiment Matplotlib plots](../img/manual_matplotlib_reporting_01.png)
+
+Matplotlib figures can be logged as images by passing `report_image=True` to `Logger.report_matplotlib_figure()`. 
+View the images in the experiment's **DEBUG SAMPLES** tab.
+
+![Experiment debug sample](../img/manual_matplotlib_reporting_03.png)
+
+See [Manual Matplotlib Reporting](../guides/reporting/manual_matplotlib_reporting.md) example.
+

sidebars.js

@@ -63,7 +63,7 @@ module.exports = {
                 'integrations/catboost', 'integrations/click', 'guides/frameworks/fastai/fastai_with_tensorboard',
                 'integrations/hydra',
                 'guides/frameworks/keras/keras_tensorboard', 'guides/frameworks/tensorflow/integration_keras_tuner',
-                'guides/frameworks/lightgbm/lightgbm_example', 'guides/frameworks/matplotlib/matplotlib_example',
+                'guides/frameworks/lightgbm/lightgbm_example', 'integrations/matplotlib',
                 'guides/frameworks/megengine/megengine_mnist', 'integrations/openmmv', 'integrations/optuna',
                 'integrations/python_fire', 'guides/frameworks/pytorch/pytorch_mnist',
                 'integrations/ignite',