Improved docs

docs/en/plugins/atoum.md

@@ -1,6 +1,11 @@
+Plugin Atoum
+------------
+
 Allows you to run [Atoum](https://github.com/atoum/atoum) unit tests.
 
-## Configuration
+Configuration
+=============
+
 ### Options
 
 - **args** [string, optional] - Allows you to pass command line arguments to Atoum.
@@ -8,7 +13,7 @@ Allows you to run [Atoum](https://github.com/atoum/atoum) unit tests.
 - **directory** [string, optional] - Path in which to run Atom (defaults to the build root).
 - **executable** [string, optional] - Allows you to provide a path to the Atom binary (defaults to PHPCI root, vendor/bin, or a system-provided Atom binary).
 
-### Example
+### Examples
 ```yml
   test:
     atoum:

docs/en/plugins/behat.md

@@ -1,11 +1,17 @@
+Plugin Behat
+------------
+
 A very simple plugin for running [Behat](http://behat.org/) BDD tests.
 
-## Configuration
+Configuration
+=============
+
 ### Options
+
 - **executable** [string, optional] - Allows you to provide a path to the Behat binary (defaults to PHPCI root, vendor/bin, or a system-provided Behat binary).
 - **features** [string, optional] - Provide a list of Behat features to run.
 
-### Example
+### Examples
 ```yml
   test:
     behat:

docs/en/plugins/campfire.md

@@ -1,13 +1,19 @@
+Plugin Campfire
+---------------
+
 This plugin joins a [Campfire](https://campfirenow.com/) room and sends a user-defined message, for example a "Build Succeeded" message.
 
-## Configuration
+Configuration
+=============
+
 ### Options
+
 - **authToken** [string, required] - Your Campfire user authentication token.
 - **message** [string, required] - The message to send to the room.
 - **roomId** [string, required] - Your Campfire room ID number.
 - **url** [string, required] - Your Campfire chat room URL.
 
-### Example
+### Examples
 ```yml
   build_settings:
     campfire:

docs/en/plugins/clean_build.md

@@ -1,10 +1,16 @@
+Plugin Clean build
+------------------
+
 Works through a list of files to remove from your build. Useful when used in combination with Copy Build or Package Build.
 
-### Configuration Options:
+Configuration
+=============
+
+### Options
 
 * **remove** - Required - An array of files and / or directories to remove.
 
-### Example Configuration:
+### Examples
 
 ```yml
 complete:

docs/en/plugins/codeception.md

@@ -1,6 +1,12 @@
+Plugin Codeception
+------------------
+
 A simple plugin that allows you to run [Codeception](http://codeception.com/) tests.
 
-### Configuration Options:
+Configuration
+=============
+
+### Options
 
 * **config** - Required - Can be either a single string pointing to a Codeception configuration file, or an array of configuration file paths. By default this is called `codeception.yml` and will be in the root of your project.
 
@@ -8,7 +14,7 @@ A simple plugin that allows you to run [Codeception](http://codeception.com/) te
 
 * **path** - Optional - The path from the root of your project to the root of the codeception _output directory
 
-##### Default values
+#### Default values
 
 - config
  - `codeception.yml` if it exists in the root of the project
@@ -21,7 +27,9 @@ A simple plugin that allows you to run [Codeception](http://codeception.com/) te
 - path
  - `tests/_output/`
 
-##### Example on running codeception with default settings (when tests are in tests/ directory):
+### Examples
+
+#### Example on running codeception with default settings (when tests are in tests/ directory):
 
 ```
   codeception:
@@ -29,7 +37,7 @@ A simple plugin that allows you to run [Codeception](http://codeception.com/) te
     path: "tests/"
 ```
 
-##### Example usage against the Yii2 framework
+#### Example usage against the Yii2 framework
 
 ```
 codeception:

docs/en/plugins/composer.md

@@ -1,12 +1,22 @@
+Plugin Composer
+---------------
+
 Allows you to run Composer within your build, to install dependencies prior to testing. Best run as a "setup" stage plugin.
 
-## Configuration
+Configuration
+=============
+
 ### Options
+
 * **directory** [optional, string] - Directory within which you want Composer to run (default: build root) 
 * **action** [optional, string, update|install] - Action you wish Composer to run (default: 'install')
 * **prefer_dist** [optional, bool, true|false] - whether Composer should run with the `--prefer-dist` flag (default: false)
+* **prefer_source** [optional, bool, true|false] - whether Composer should run with the `--prefer-source` flag (default: false)
+* **no_dev** [optional, bool, true|false] - whether Composer should run with the `--no-dev` flag (default: false)
+* **ignore_platform_reqs** [optional, bool, true|false] - whether Composer should run with the `--ignore-platform-reqs` flag (default: false)
+
+### Examples
 
-### Example
 ```yml
 setup:
   composer:
@@ -15,7 +25,8 @@ setup:
     prefer_dist: true
 ```
 
-## Warning
+Warning
+=======
 
 If you are using a Composer private repository like Satis, with HTTP authentication, you must check your username and password inside the ```auth.json``` file. PHPCI uses the ```--no-interaction``` flag, so it will not warn if you must provide that info.
 

docs/en/plugins/copy_build.md

@@ -1,6 +1,12 @@
+Plugin Copy Build
+-----------------
+
 Copies all files from your build, with the exception of those in the "ignore" build settings property, to a directory of your choosing.
 
-### Configuration Options:
+Configuration
+=============
+
+### Options
 
 * **directory** - Required - The directory to which you want to copy the build.
 * **respect_ignore** - Optional - Whether to respect the global "ignore" setting when copying files. Default is false.

docs/en/plugins/deployer.md

@@ -1,12 +1,19 @@
+Plugin Deployer
+---------------
+
 Triggers a deployment of the project to run via [Deployer](http://phpdeployment.org)
 
-**Configuration Options:**
+Configuration
+=============
+
 ### Options
+
 * **webhook_url** [required, string] - The URL to your Deployer WebHook 
 * **reason** [optional, string] - Your deployment message. Default - PHPCI Build #%BUILD% - %COMMIT_MESSAGE%
 * **update_only** [optional, bool, true|false] - Whether the deployment should only be run if the currently deployed branches matches the one being built. Default - true
 
-### Example
+### Examples
+
 ```yaml
 success:
     deployer:

docs/en/plugins/email.md

@@ -1,6 +1,12 @@
+Plugin Email
+------------
+
 Sends a build status email.
 
-### Configuration Options:
+Configuration
+=============
+
+### Options
 
 * **committer** - Whether or not to send the email to the committer that prompted this build.
 * **addresses** - A list of addresses to send to.
@@ -11,7 +17,8 @@ Sends a build status email.
 
 **Note:** _This plugin will only work if you configured email settings during installation or configured them later in Admin Options > Settings > Email Settings_
 
-### Configuration Example
+### Examples
+
 See [Adding PHPCI Support to Your Projects](https://www.phptesting.org/wiki/Adding-PHPCI-Support-to-Your-Projects) for more information about how to configure plugins.
 
 Send an email to the committer as well as one@exameple.com if a build fails:

docs/en/plugins/env.md

@@ -1,6 +1,12 @@
+Plugin Env
+----------
+
 Sets environment variables on the PHPCI server for the build.
 
-### Sample Configuration:
+Configuration
+=============
+
+### Examples:
 
 ```yml
 setup:

docs/en/plugins/grunt.md

@@ -1,13 +1,20 @@
+Plugin Grunt
+------------
+
 This plugin runs [Grunt](http://gruntjs.com/) tasks.
 
-## Configuration
+Configuration
+=============
+
 ### Options
+
 - **directory** [string, optional] - The directory in which to run Grunt (defaults to build root.)
 - **grunt** [string, optional] -  Allows you to provide a path to Grunt (defaults to PHPCI root, vendor/bin, or a system-provided Grunt).
 - **gruntfile** [string, optional] - Gruntfile to run (defaults to `Gruntfile.js`).
 - **task** [string, optional] - The Grunt task to run.
 
 ### Example
+
 ```yml
   test:
     grunt:

docs/en/plugins/hipchat_notify.md

@@ -1,6 +1,12 @@
+Plugin Hipchat Notify
+---------------------
+
 This plugin joins a [HipChat](https://www.hipchat.com/) room and sends a user-defined message, for example a "Build Succeeded" message.
 
-**Configuration Options:**
+Configuration
+=============
+
+### Options
 
 | Field | Required? | Description |
 |-------|-----------|-------------|
@@ -15,7 +21,8 @@ Message can be formatted via HTML. Example:
 <b>%PROJECT_TITLE%</b> - build <a href="%BUILD_URI%">%BUILD%</a> failed!
 ```
 
-Configuration example: 
+### Examples
+
 ```yaml
 hipchat_notify:
     authToken: 123

docs/en/plugins/irc.md

@@ -1,10 +1,16 @@
+Plugin IRC
+----------
+
 Connects to an IRC server and sends a defined message.
 
-### Configuration Options:
+Configuration
+=============
+
+### Options
 
 * **message** - Required - The message to send.
 
-### Build Settings
+#### Build Settings
 
 * **irc** - All child properties are required
     * **server** - IRC server to connect to.

docs/en/plugins/lint.md

@@ -1,12 +1,19 @@
+Plugin Lint
+-----------
+
 This plugin runs PHP's built in Lint (syntax / error check) functionality.
 
-## Configuration
+Configuration
+=============
+
 ### Options
+
 - **directory** [string, optional] - A single path in which you wish to lint files.
 - **directories** [array, optional] - An array of paths in which you wish to lint files. This overrides  `directory`.
 - **recursive** [bool, optional] - Whether or not you want to recursively check sub-directories of the above (defaults to true).
 
-### Example
+### Examples
+
 ```yml
   test:
     lint:

docs/en/plugins/mysql.md

@@ -1,6 +1,12 @@
+Plugin MySQL
+------------
+
 Connects to a given MySQL server and runs a selection of queries.
 
-### Example Configuration:
+Configuration
+=============
+
+### Examples
 
 ```yaml
 build_settings:

docs/en/plugins/package_build.md

@@ -1,6 +1,12 @@
+Plugin Package Build
+--------------------
+
 Builds a tar or zip archive of your build and places it in a directory of your choosing.
 
-### Configuration Options:
+Configuration
+=============
+
+### Options
 
 * **directory** - Required - Directory in which to put the package file.
 * **filename** - Required - File name for the package.

docs/en/plugins/pdepend.md

@@ -1,5 +1,11 @@
+Plugin Pdepend
+--------------
+
 Runs [PDepend](http://pdepend.org/) software metrics.
 
-### Configuration Options:
+Configuration
+=============
+
+### Options
 
 * **directory** - Required - Directory in which to run PDepend.

docs/en/plugins/pgsql.md

@@ -1,6 +1,12 @@
+Plugin PostgreSQL
+-----------------
+
 Connects to a given PostgreSQL server and runs a list of queries.
 
-### Example Configuration:
+Configuration
+=============
+
+### Examples
 
 ```yaml
 build_settings:

docs/en/plugins/phar.md

@@ -1,6 +1,19 @@
+Plugin Phar
+-----------
+
 Allows you to create a [Phar](http://php.net/manual/en/book.phar.php) archive from your project.
 
-### Example
+Configuration
+=============
+
+### Options
+
+* **directory**: `phar` output directory. Default: `%buildpath%`;
+* **filename**: `phar` filename inside output directory. Default: `build.phar`;
+* **regexp**: regular expression for Phar iterator. Default: `/\.php$/`; and
+* **stub**: stub content filename. No default value.
+
+### Examples
 
 ```
 phar:
@@ -9,10 +22,3 @@ phar:
     regexp: /\.(php|phtml)$/
     stub: filestub.php
 ```
-
-### Configuration Options
-
-* **directory**: `phar` output directory. Default: `%buildpath%`;
-* **filename**: `phar` filename inside output directory. Default: `build.phar`;
-* **regexp**: regular expression for Phar iterator. Default: `/\.php$/`; and
-* **stub**: stub content filename. No default value.

docs/en/plugins/phing.md

@@ -1,13 +1,21 @@
+Plugin Phing
+------------
+
 This plugin allows you to use the Phing build system to build your project.
 
-### Configuration options:
+Configuration
+=============
+
+### Options
+
 * **directory** - Relative path to the directory in which you want to run phing.
 * **build_file** - Your phing build.xml file.
 * **targets** - Which build targets you want to run.
 * **properties** - Any custom properties you wish to pass to phing.
 * **property_file** - A file containing properties you wish to pass to phing.
 
-### Sample config:
+### Examples
+
 ```yml
 phing:
       build_file: 'build.xml'

docs/en/plugins/php_code_sniffer.md

@@ -1,7 +1,13 @@
+Plugin PHP Code Sniffer
+-----------------------
+
 Runs PHP Code Sniffer against your build.
 
-## Configuration
+Configuration
+=============
+
 ### Options
+
 * **allowed_warnings** [int, optional] - The warning limit for a successful build.
 * **allowed_errors** [int, optional] - The error limit for a successful build.
 * **suffixes** [array, optional] - An array of file extensions to check.
@@ -11,7 +17,8 @@ Runs PHP Code Sniffer against your build.
 * **path** [string, optional] - Path in which to run PHP Code Sniffer.
 * **ignore** [array, optional] - A list of files / paths to ignore, defaults to the build_settings ignore list.
 
-### Example
+### Examples
+
 Simple example where PHPCS will run on app directory, but ignore the views folder, and use PSR-1 and PSR-2 rules for validation:
 ```yml
 test:

docs/en/plugins/php_cpd.md

@@ -1,12 +1,18 @@
-Runs PHP Copy / Paste Detector against your build.
+Plugin PHP Copy/Paste Detector
+------------------------------
+
+Runs PHP Copy/Paste Detector against your build.
+
+Configuration
+=============
 
-## Configuration
 ### Options
+
 * **path** - Optional - Path in which to run PHP Copy/Paste Detector (default: build root).
 * **ignore** - Optional - A list of files / paths to ignore (default: build_settings > ignore).
 * **standard** [string, optional] - which PSR standard to follow (default: 'PSR1').
 
-### Example
+### Examples
 
 ```yml
 test:

docs/en/plugins/php_cs_fixes.md

@@ -1,13 +1,20 @@
+Plugin PHP Coding Standards Fixer
+---------------------------------
+
 Runs PHP Coding Standards Fixer against your build.
 
-## Configuration
+Configuration
+=============
+
 ### Options
+
 * **verbose** [bool, optional] - Whether to run in verbose mode (default: false)
 * **diff** [bool, optional] - Whether to run with the `--diff` flag enabled (default: false)
 * **level** [string, optional] - `psr0`, `psr1`, `psr2`, or `symphony` (default: all)
 * **workingdir** [string, optional] - The directory in which PHP CS Fixer should work (default: build root)
 
-### Example
+### Examples
+
 ```yml
 test:
   php_cs_fixer:
@@ -17,5 +24,7 @@ test:
     workingdir: "my/dir/path"
 ```
 
-## Warning
+Warning
+=======
+
 There is currently a bug with this plugin that will cause an error if you leave the level to default to `all`. That level does not exist and will cause the build to fail. Instead specify the level explicitly until this is fixed.

docs/en/plugins/php_docblock_checker.md

@@ -1,13 +1,19 @@
+Plugin PHP Docblock Checker
+---------------------------
+
 Runs the PHP Docblock Checker against your build. This tool verifies that all classes and methods have docblocks.
 
-### Configuration Options:
+Configuration
+=============
+
+### Options
 
 * **allowed_warnings** - Optional - The warning limit for a successful build.
 * **path** - Optional - Directory in which PHP Docblock Checker should run.
 * **skip_methods** - Optional - Tells the checker to ignore methods that don't have a docblock.
 * **skip_classes** - Optional - Tells the checker to ignore classes that don't have a docblock.
 
-### Example config:
+### Examples
 
 ```yml
 php_docblock_checker:

docs/en/plugins/php_loc.md

@@ -1,10 +1,17 @@
+Plugin PHPLoc
+-------------
+
 Runs [PHPLoc](https://github.com/sebastianbergmann/phploc) against your project and records some key metrics.
 
-## Configuration
+Configuration
+=============
+
 ### Options
+
 * **directory** - Optional - The directory in which phploc should run. 
 
 ### Example
+
 Run PHPLOC against the app directory only. This will prevent inclusion of code from 3rd party libraries that are included outside of the app directory.
 
 ```yml

docs/en/plugins/php_mess_detector.md

@@ -1,7 +1,13 @@
+Plugin PHP Mess Detector
+------------------------
+
 Runs PHP Mess Detector against your build. Records some key metrics, and also reports errors and warnings.
 
-## Configuration
+Configuration
+=============
+
 ### Options
+
 - **allowed_warnings** [int, optional] - The warning limit for a successful build (default: 0). -1 disables warnings. Setting allowed_warnings in conjunction with zero_config will override zero_config.
 - **suffixes** [array, optional] - An array of file extensions to check (default: 'php')
 - **ignore** [array, optional] - An array of files/paths to ignore (default: build_settings > ignore)
@@ -9,8 +15,8 @@ Runs PHP Mess Detector against your build. Records some key metrics, and also re
 - **rules** [array, optional] - Array of rulesets that PHPMD should use when checking your build or a string containing at least one slash, will be treated as path to PHPMD ruleset. See http://phpmd.org/rules/index.html for complete details on the rules. (default: ['codesize', 'unusedcode', 'naming']).
 - **zero_config** [bool, optional] - Suppresses build failure on errors and warnings if set to true. (default: false).
 
+### Examples
 
-### Example
 ```yml
 test:
   php_mess_detector:

docs/en/plugins/php_parallel_lint.md

@@ -1,11 +1,18 @@
+Plugin PHP Parallel Lint
+------------------------
+
 Similar to the [standard PHP Lint plugin](https://github.com/Block8/PHPCI/wiki/Lint-plugin), except that it uses the [PHP Parallel Lint](https://github.com/JakubOnderka/PHP-Parallel-Lint) project to run.
 
-## Configuration
+Configuration
+=============
+
 ### Options
+
 * **directory** [string, optional] - directory to inspect (default: build root)
 * **ignore** [array, optional] - directory to ignore (default: inherits ignores specified in setup)
 
-### Example
+### Examples
+
 ```yml
 test:
   php_parallel_lint:

docs/en/plugins/php_spec.md

@@ -1,24 +1,18 @@
+Plugin PHP Spec
+---------------
+
 Runs [PHP Spec](http://www.phpspec.net/) tests against your build.
 
-### Configuration Options:
+Configuration
+=============
+
+### Options
 
 * **bootstrap** - Optional - Path to a PHPSpec bootstrap file. 
 
-### Example
+### Examples
 
 ```
-build_settings:
-    [...]
-
-setup:
-    [...]
-
 test:
     php_spec:
-
-complete:
-    [...]
-
-success:
-    [...]
 ```

docs/en/plugins/php_unit.md

@@ -1,9 +1,17 @@
+Plugin PHPUnit
+--------------
+
 Runs PHPUnit tests against your build.
-## Configuration
+
+Configuration
+=============
+
 ### Options
+
 Has two modes:
 
 #### phpunit.xml Configuration File
+
 Its activated if you have phpunit.xml file in your build path, `tests/` subfolder, or you specify it as a parameter:
 * **config** - Optional - Path to a PHP Unit XML configuration file.
 * **run_from** - Optional - When running PHPUnit with an XML config, the command is run from this directory
@@ -11,12 +19,14 @@ Its activated if you have phpunit.xml file in your build path, `tests/` subfolde
 * **path** - Optional - In cases where tests files are in a sub path of the /tests path, allows this path to be set in the config.
 
 #### Running Tests By Specifying Directory
+
 * **directory** - Optional - The directory (or array of dirs) to run PHPUnit on
 
 Both modes accept:
 * **args** - Optional - Command line args (in string format) to pass to PHP Unit
 
 ### Examples
+
 Specify config file and test directory:
 ```yml
 test:
@@ -26,7 +36,9 @@ test:
         path: "app/tests/"
 ```
 
-## Troubleshooting
+Troubleshooting
+===============
+
 If standard logging of PHPCI is not enough, to get standard output from any command, including PHPUnit, edit `BaseCommandExecutor::executeCommand()` to see what exactly is wrong
 * Run `composer update` in phpunit plugin directory of PHPCI to get all of its dependencies
 * If phpunit is inside of the project's composer.json, it might interfere with PHPCI's phpunit installation

docs/en/plugins/shell.md

@@ -1,3 +1,6 @@
+Plugin Shell
+------------
+
 Runs a given Shell command.
 
 **Note: ** Because this plugin could potentially be abused, it requires extra steps to enable it:
@@ -13,7 +16,10 @@ define('ENABLE_SHELL_PLUGIN', true);
 
 If `ENABLE_SHELL_PLUGIN` is either false or undefined, the shell plugin won't work.
 
-### Configuration Options:
+Configuration
+=============
+
+### Options
 
 * **command** - Required - The shell command to run.
 
@@ -24,7 +30,7 @@ setup:
 ```
  You should understand, that in old configuration type, you can run only one command!
 
-### New format of Configuration Options
+#### New format of Configuration Options
 
 ```yml
 setup:
@@ -44,5 +50,4 @@ setup:
         - "cd %BUILD_PATH% && php artisan migrate" # Laravel Migrations
 ```
 
-
 [See variables which you can use in shell commands](../interpolation.md)

docs/en/plugins/slack_notify.md

@@ -1,6 +1,12 @@
+Plugin Slack Notify
+-------------------
+
 This plugin joins a [Slack](https://www.slack.com/) room and sends a user-defined message, for example a "Build Succeeded" message.
 
-**Configuration Options:**
+Configuration
+=============
+
+### Options
 
 | Field | Required? | Description |
 |-------|-----------|-------------|
@@ -11,6 +17,8 @@ This plugin joins a [Slack](https://www.slack.com/) room and sends a user-define
 | `message`   | No | The message to send to the room. Default - `<%PROJECT_URI%|%PROJECT_TITLE%> - <%BUILD_URI%|Build #%BUILD%> has finished for commit <%COMMIT_URI%|%SHORT_COMMIT% (%COMMIT_EMAIL%)> on branch <%BRANCH_URI%|%BRANCH%>` |
 | `show_status` | No | Whether or not to append the build status as an attachment in slack. Default - true
 
+### Examples
+
 Send a message if the build fails:
 ```yaml
 failure:
@@ -47,4 +55,4 @@ complete:
         icon: ":ghost:"
         message: "%PROJECT_TITLE% - build %BUILD% completed"
         show_status: true
-```
+```

docs/en/plugins/technical_dept.md

@@ -1,5 +1,11 @@
+Plugin Technical Dept
+---------------------
+
 Checks all files in your project for TODOs and other technical debt.
 
-## Configuration Options:
+Configuration
+=============
+
+### Options
 
 * **searches** - Optional - Case-insensitive array of terms to search for. Defaults to TODO, TO DO, FIXME and FIX ME.

docs/en/plugins/xmpp.md

@@ -1,11 +1,22 @@
-## Requirements
+Plugin XMPP
+-----------
+
+Requirements
+============
+
 - sendxmpp package 
 
-## Installation
+Installation
+============
+
 1. On debian system (for example) use aptitude command to install sendxmpp 
 2. Add XMPP plugin in "complete" section of your phpci.yml
 
-## Configuration options
+Configuration
+=============
+
+### Options
+
 - username : Username of your XMPP sender account. (example : login@server.com)
 - password : Password of your XMPP sender account.
 - recipients : List of your XMPP recipents account.
@@ -14,7 +25,7 @@
 - alias : Alias of your sender account. (optional)
 - date_format : strftime mask date format display in notification message. (optional, default is %c of strftime function)
 
-## Configuration example
+### Examples
 
 ```
 complete: