minor #11398 [Frontend] Add doc Watch Options configuration (Kocal)

This PR was submitted for the master branch but it was squashed and merged into the 3.4 branch instead (closes #11398).

Discussion
----------

[Frontend] Add doc Watch Options configuration

Hi,

This PR add a new page that shows how to easily configure watching options with Encore:
```js
Encore.configureWatchOptions(watchOptions => {
  watchOptions.poll = 250;
});
```

I've also reworked the Advanced Config page to remove the old way to configure watch options.

Thanks!

Commits
-------

da27286 [Frontend] Add doc Watch Options configuration

Author: javiereguiluz

frontend.rst

@@ -73,6 +73,7 @@ Guides
 * :doc:`Passing Information from Twig to JavaScript </frontend/encore/server-data>`
 * :doc:`webpack-dev-server and Hot Module Replacement (HMR) </frontend/encore/dev-server>`
 * :doc:`Adding custom loaders & plugins </frontend/encore/custom-loaders-plugins>`
+* :doc:`Configuring Watching Options and Polling </frontend/encore/watch-options>`
 * :doc:`Advanced Webpack Configuration </frontend/encore/advanced-config>`
 
 Issues & Questions

frontend/encore/advanced-config.rst

@@ -5,10 +5,8 @@ Summarized, Encore generates the Webpack configuration that's used in your
 ``webpack.config.js`` file. Encore doesn't support adding all of Webpack's
 `configuration options`_, because many can be added on your own.
 
-For example, suppose you need to set `Webpack's watchOptions`_ setting. To do that,
-modify the config after fetching it from Encore:
-
-.. TODO update the following config example when https://github.com/symfony/webpack-encore/pull/486 is merged and configureWatchOptions() is introduced
+For example, suppose you need to resolve automatically a new extension.
+To do that, modify the config after fetching it from Encore:
 
 .. code-block:: javascript
 
@@ -20,14 +18,9 @@ modify the config after fetching it from Encore:
 
     // fetch the config, then modify it!
     var config = Encore.getWebpackConfig();
-    // if you run 'encore dev --watch'
-    config.watchOptions = { poll: true, ignored: /node_modules/ };
-    // if you run 'encore dev-server'
-    config.devServer.watchOptions = { poll: true, ignored: /node_modules/ };
 
-    // other examples: add an alias or extension
-    // config.resolve.alias.local = path.resolve(__dirname, './resources/src');
-    // config.resolve.extensions.push('json');
+    // add an extension
+    config.resolve.extensions.push('json');
 
     // export the final config
     module.exports = config;
@@ -212,6 +205,5 @@ The following loaders are configurable with ``configureLoaderRule()``:
   - ``handlebars``
 
 .. _`configuration options`: https://webpack.js.org/configuration/
-.. _`Webpack's watchOptions`: https://webpack.js.org/configuration/watch/#watchoptions
 .. _`array of configurations`: https://github.com/webpack/docs/wiki/configuration#multiple-configurations
 .. _`Karma`: https://karma-runner.github.io

frontend/encore/watch-options.rst

@@ -0,0 +1,14 @@
+Configuring Watching Options and Polling
+========================================
+
+Encore provides the method ``configureWatchOptions()`` to configure `Watching Options`_ when running ``encore dev --watch`` or ``encore dev-server``:
+
+.. code-block:: javascript
+
+    Encore.configureWatchOptions(function(watchOptions) {
+        // enable polling and check for changes every 250ms
+        // polling is useful when running Encore inside a Virtual Machine
+        watchOptions.poll = 250;
+    });
+
+.. _`Watching Options`: https://webpack.js.org/configuration/watch/#watchoptions