docs: new grunt-like config format

docs/config/01-configuration-file.md

@@ -1,6 +1,22 @@
 In order to serve you well, Karma needs to know about your
 project. That's done through a configuration file.
 
+Karma config files are Node modules which are
+[required](http://nodejs.org/api/modules.html#modules_module_require_id) and
+are expected to export a function which accepts one argument -- Karma dsl
+object. Karma DSL object exposes [configure] method which can be called to set
+karma properties. For example:
+
+```javascript
+module.exports = function(karma) {
+  karma.configure({
+    basePath: '../..',
+    frameworks: ['jasmine'],
+    //...
+  });
+};
+```
+
 For an example configuration, see [test/client/karma.conf.js]
 which contains most of the options.
 
@@ -103,17 +119,17 @@ See [config/files] for more information.
 ## logLevel
 **Type:** Constant
 
-**Default:** `LOG_INFO`
+**Default:** `karma.LOG_INFO`
 
 **CLI:** `--log-level debug`
 
 **Possible values:**
 
-  * `LOG_DISABLE`
-  * `LOG_ERROR`
-  * `LOG_WARN`
-  * `LOG_INFO`
-  * `LOG_DEBUG`
+  * `karma.LOG_DISABLE`
+  * `karma.LOG_ERROR`
+  * `karma.LOG_WARN`
+  * `karma.LOG_INFO`
+  * `karma.LOG_DEBUG`
 
 **Description:** Level of logging.
 
@@ -154,10 +170,10 @@ See [config/files] for more information.
 
 **Example:**
   ```javascript
-  proxies =  {
+  proxies:  {
     '/static': 'http://gstatic.com',
     '/web': 'http://localhost:9000'
-  };
+  },
   ```
 
 ## reportSlowerThan

docs/config/02-files.md

@@ -14,10 +14,10 @@ If you want to use any of these, add `<FRAMEWORK>` and
 `<FRAMEWORK>_ADAPTER` to your `files` list. So for example if you want
 to use Mocha you have the following in your config file:
 ```javascript
-files = [
+files: [
   MOCHA,
   MOCHA_ADAPTER
-];
+],
 ```
 
 ## Pattern matching and `basePath`
@@ -67,7 +67,7 @@ If you define them like before a simple pattern like
 ## Complete example
 Here is a complete example showing the different options that are possible.
 ```javascript
-files = [
+files: [
 
   // Adapter
   MOCHA,
@@ -82,7 +82,7 @@ files = [
 
   // this file only gets watched but otherwise ignored
   {pattern: 'app/index.html', included: false, served: false}
-];
+],
 ```
 
 [glob]: https://github.com/isaacs/node-glob

docs/config/03-browsers.md

@@ -3,7 +3,7 @@ Capturing browsers is kinda boring, so Karma can do that for you.
 Just simply add into the configuration file:
 
 ```javascript
-browsers = ['Chrome'];
+browsers: ['Chrome'],
 ```
 Then, Karma will take care of autocapturing these browsers, as
 well as killing them.
@@ -53,7 +53,7 @@ $Env:FIREFOX_BIN = 'c:\Program Files (x86)\Mozilla Firefox 4.0 Beta 6\firefox.ex
 ## Custom browsers
 ```javascript
 // in the karma.conf.js
-browsers = ['/usr/local/bin/custom-browser.sh'];
+browsers: ['/usr/local/bin/custom-browser.sh'],
 
 // from cli
 karma start --browsers /usr/local/bin/custom-browser.sh

docs/config/04-preprocessors.md

@@ -3,10 +3,10 @@ they get served to the browser. The configuration of these happens in this block
 in the config file.
 
 ```javascript
-preprocessors = {
+preprocessors: {
   '**/*.coffee': 'coffee',
   '**/*.html': 'html2js'
-};
+},
 ```
 
 ## Available Preprocessors

docs/config/05-coverage.md

@@ -12,25 +12,25 @@ For example if all your code lives in ``lib/`` you need to add this to your
 configuration file.
 
 ```javascript
-preprocessors = {
+preprocessors: {
   '**/lib/*.js': 'coverage'
-};
+},
 ```
 You should not however include the files that aren't directly related to your
 program, e.g. libraries, mocks, neither tests.
 
 This is a **BAD** example
 
 ```javascript
-files = [
+files: [
   JASMINE,
   JASMINE_ADAPTER,
   'lib/*.js',
   'test/*.js'
-];
-preprocessors = {
+],
+preprocessors: {
   '**/*.js': 'coverage'
-};
+},
 ```
 In this example also JASMINE and JASMINE_ADAPTER get included but they shouldn't as
 these file are only for the test setup used and not for your program.
@@ -43,7 +43,7 @@ If you include these files there can occur side effects like the following,
 ## Reporter
 To activate the coverage reporter add this to your configuration file.
 ```javascript
-reporters = ['coverage'];
+reporters: ['coverage'],
 ```
 This will create a coverage report for every browser that the tests are run in.
 In addition, it will create a JSON file that outputs the intermediate data.
@@ -53,10 +53,10 @@ In addition, it will create a JSON file that outputs the intermediate data.
 The reporter defaults to the following values.
 
 ```javascript
-coverageReporter = {
+coverageReporter: {
   type : 'html',
   dir : 'coverage/'
-}
+},
 ```
 If you want to configure it yourself here are the options explained.
 
@@ -73,11 +73,11 @@ If you want to configure it yourself here are the options explained.
 
 If you set `type` to `text` or `text-summary`, you may set the `file` option, like this.
 ```javascript
-coverageReporter = {
+coverageReporter: {
   type : 'text',
   dir : 'coverage/',
   file : 'coverage.txt'
-}
+},
 ```
 If no filename is given, it will write the output to the console.
 

docs/plus/02-RequireJS.md

@@ -62,7 +62,7 @@ Now your `karma.conf.js` should include:
 
 ```javascript
 // list of files / patterns to load in the browser
-files = [
+files: [
   JASMINE,
   JASMINE_ADAPTER,
   REQUIRE,
@@ -73,12 +73,12 @@ files = [
   {pattern: 'test/**/*Spec.js', included: false},
 
   'test/test-main.js'
-];
+],
 
 // list of files to exclude
-exclude = [
+exclude: [
     'src/main.js'
-];
+],
 ```
 
 ## Configuring Require.js

docs/plus/03-Jenkins-CI.md

@@ -23,11 +23,11 @@ distributions and user permissions.
  file as needed:
 
 ```javascript
-singleRun = true;
-reporters = ['dots', 'junit'];
-junitReporter = {
+singleRun: true,
+reporters: ['dots', 'junit'],
+junitReporter: {
   outputFile: 'test-results.xml'
-};
+},
  ```
 
 Please note the `test-result.xml` file will be output to the present

docs/plus/05-Cloud9.md

@@ -16,10 +16,10 @@ PhantomJS must be installed with `npm install phantomjs`.
 The `karma.conf.js` file (tried it out for the [AngularJS foodme app]) must include the following entries:
 
 ```javascript
-browsers = ['PhantomJS'];
-hostname = process.env.IP;
-port = process.env.PORT;
-runnerPort = 0;
+browsers: ['PhantomJS'],
+hostname: process.env.IP,
+port: process.env.PORT,
+runnerPort: 0,
 ```
 
 [Cloud9 IDE]: https://c9.io/