docs: Emphasise that merge() doesn't accept webpack config objects

[edmorley]

The data structure that is passed to .merge() is very similar to a webpack configuration object, but has a few key differences.

The current docs don't make this clear enough, such that some users have been trying to pass the output of .toConfig() back to .merge(), which can cause errors:
#204 (comment)

[edmorley]

@neutrinojs/core-contributors Hi!

In addition to the wording change currently in this PR, I was wondering about drastically simplifying the .merge() section of the docs, so that instead of being a copy-paste of every webpack config option, it only listed the areas where the data structure differed from the real webpack config schema (plus perhaps a few examples from the options that were identical).

ie:

  // Differences from webpack config

  plugin: {
    [name]: {
      plugin: WebpackPlugin,
      args: [...args],
      before,
      after
    }
  },

  // All other configuration is the same

  devServer: {
    [key]: value,

    // For example:
    port: 5000,
  },

This would save us having to constantly keep the options up to date (there are many already missing, and if I add them in, this section of the docs is going to get even longer), and perhaps make it more obvious to users what the differences are (and so what parts of the config they need to transform themselves first).

[edmorley]

@neutrinojs/core-contributors (or anyone else) any thoughts on the above? :-)

[timkelty]

I was wondering about drastically simplifying the .merge() section of the docs, so that instead of being a copy-paste of every webpack config option, it only listed the areas where the data structure differed from the real webpack config schema (plus perhaps a few examples from the options that were identical).

Totally agree. Want to add that to your PR?

[timkelty]

This LGTM.
I'm in favor of truncating the .merge docs as mentioned as well.

[edmorley]

I've split out the further example simplifications idea to #237 so that we can merge this in the meantime :-)