Documentation refactoring

README.md

@@ -3,19 +3,64 @@
 ## Description
 
 This module adds a Debug Toolbar in Magento 2.
+The toolbar displays useful information about the last executions (including ajax requests, rest API and graphql):
 
-**Use it only on dev environment.**
+- HTTP Request/response
+- SQL queries (with the PHP trace for each query)
+- Profiler information (with timers)
+- Layout information
+- Cached items
+- Plugins/observers that were triggered
 
-The toolbar displays useful information about the last executions, including redirects, Ajax calls, WebApi calls, and ESI calls.
+![](doc/images/toolbar.png)
 
-It allows you to analyze the SQL queries, the layout, the plugins, ...
+## Installation
 
-## Documentation
+To install the module:
 
-1. [Installation](doc/install.md)
-2. [Back-Office](doc/backoffice.md)
-3. [Toolbar](doc/toolbar.md)
-4. [How-To](doc/howto.md)
+1. Execute the following command at the root of the Magento installation:
+    ```bash
+    composer require --dev smile/module-debug-toolbar
+    ```
+2. Enable the module:
+    ```bash
+    bin/magento module:enable Smile_DebugToolbar
+    bin/magento setup:upgrade
+    ```
+3. Enable the toolbar:
+    ```
+    bin/magento config:set smile_debugtoolbar/configuration/enabled 1
+    ```
+
+## Configuration
+
+The configuration of the module is available in the section **Smile > Smile DebugToolbar** of the admin area:
+
+You can:
+
+- Enable / disable the debug toolbar (default: disabled)
+- Show / hide the debug toolbar in the admin area (default: hidden)
+- Choose the number of last executions to save and display in the toolbar (default: 5)
+
+## Uninstallation
+
+Unfortunately, the module cannot be automatically uninstalled, because Magento doesn't support uninstallation of dev packages out of the box.
+
+To uninstall the module, follow these steps:
+
+1. In app/etc/env.php, remove the key `db.connection.default.profiler` from the array if it is defined.
+2. Run the following commands:
+    ```
+    bin/magento module:disable Smile_DebugToolbar
+    composer remove --dev smile/module-debug-toolbar
+    bin/magento setup:upgrade
+    ```
+3. [Optional] Remove the directory "var/smile_toolbar".
+
+## Customizing the Toolbar
+
+It is possible to add new zones to the toolbar (e.g. to display project-specific data).
+This is [documented here](doc/add-zone.md).
 
 ## Contributing
 

doc/howto.md → doc/add-zone.md

@@ -1,17 +1,16 @@
-# How To
+# How to Add Zones
 
-## Add a new zone
+It is possible add new zones (i.e. sections) to the toolbar.
+To do this, you must implement a new block associated to a template file.
 
-You can add a new zone in the toolbar.
-
-To do it, you must implement a new block associated to a template file.
-
-Your new block must:
+This new block must:
 
 - extend the class `\Smile\DebugToolbar\Block\Zone\AbstractZone`
 - implement the method `getTitle`
 - implement the method `getCode`
 
+For example:
+
 ```php
 <?php
 
@@ -41,16 +40,17 @@ class MyZone extends AbstractZone
 }
 ```
 
-It must be associated to the template file `./view/base/templates/zone/myzone.phtml` of your module:
+It must be associated to the template file `view/base/templates/zone/myzone.phtml` of your module:
 
 ```php
 <?php
+
 /** @var \MyNameSpace\MyModule\Block\Zone\MyZone $block */
 
 $sections = [
     'Some Values' => [
         'Current Date' => $block->formatValue(date('Y-m-d H:i:s'), [], 'datetime'),
-        'Memory Used'  => $block->formatValue((int) memory_get_peak_usage(true), ['gt' => 128*1024*1024], 'size'),
+        'Memory Used' => $block->formatValue((int) memory_get_peak_usage(true), ['gt' => 128*1024*1024], 'size'),
     ],
 ];
 
@@ -61,18 +61,18 @@ echo $block->displaySections($sections);
 
 You can:
 
-- Format values, using the `formatValue` method. You can specify rules to generate automatic warnings.
-- Display sections, using the `displaySections` method.
-- Add values to the summary zone, using the `addToSummary` method.
+- Format values with the `formatValue` method.
+- Display sections with the `displaySections` method.
+- Add values to the summary zone with the `addToSummary` method.
 
-Then, you can add this new zone to the toolbar, by adding an observer on the event `smile_debug_toolbar_set_zones`.
+Then, you can add this new zone to the toolbar by adding an observer on the event `smile_debug_toolbar_set_zones`.
 
 The following objects will be available in the event:
 
 - `zones`: contains the list of the current zones.
 - `summary_block`: contains the summary zone.
 
-You can use them as follow:
+For example:
 
 ```php
 <?php
@@ -105,5 +105,3 @@ class AddZone implements ObserverInterface
     }
 }
 ```
-
-[Back](../README.md)