feature #3930 [Console] Add Process Helper documentation (romainneutron)

This PR was merged into the master branch.

Discussion
----------

[Console] Add Process Helper documentation

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | yes (symfony/symfony#10627)
| Applies to    | 2.5+
| Fixed tickets | n/a

This PR replaces #3756 (merged prematurely)

Commits
-------

a9d6a8b [Console] Add Process Helper documentation

components/console/helpers/index.rst

@@ -9,6 +9,7 @@ The Console Helpers
 
     dialoghelper
     formatterhelper
+    processhelper
     progressbar
     progresshelper
     questionhelper

components/console/helpers/map.rst.inc

@@ -1,5 +1,6 @@
 * :doc:`/components/console/helpers/dialoghelper`
 * :doc:`/components/console/helpers/formatterhelper`
+* :doc:`/components/console/helpers/processhelper`
 * :doc:`/components/console/helpers/progressbar`
 * :doc:`/components/console/helpers/progresshelper`
 * :doc:`/components/console/helpers/questionhelper`

components/console/helpers/processhelper.rst

@@ -0,0 +1,84 @@
+.. index::
+    single: Console Helpers; Process Helper
+
+Process Helper
+==============
+
+.. versionadded:: 2.6
+    The Process Helper was introduced in Symfony 2.6.
+
+The Process Helper shows processes as they're running and reports
+useful information about process status.
+
+To display process details, use the :class:`Symfony\\Component\\Console\\Helper\\ProcessHelper`
+and run your command with verbosity. For example, running the following code with
+a very verbose verbosity (e.g. -vv)::
+
+    use Symfony\Component\Process\ProcessBuilder;
+
+    $helper = $this->getHelper('process');
+    $process = ProcessBuilder::create(array('figlet', 'Symfony'))->getProcess();
+
+    $helper->run($output, $process);
+
+will result in this output:
+
+.. image:: /images/components/console/process-helper-verbose.png
+
+It will result in more detailed output with debug verbosity (e.g. ``-vvv``):
+
+.. image:: /images/components/console/process-helper-debug.png
+
+In case the process fails, debugging is easier:
+
+.. image:: /images/components/console/process-helper-error-debug.png
+
+Arguments
+---------
+
+There are three ways to use the process helper:
+
+* Either using a command line string::
+
+    // ...
+    $helper->run($output, 'figlet Symfony');
+
+* An array of arguments::
+
+    // ...
+    $helper->run($output, array('figlet', 'Symfony'));
+
+  .. note::
+
+      When running the helper against an array of arguments, be aware that
+      these ones will be automatically escaped.
+
+* Or a :class:`Symfony\\Component\\Process\\Process` instance::
+
+    use Symfony\Component\Process\ProcessBuilder;
+
+    // ...
+    $process = ProcessBuilder::create(array('figlet', 'Symfony'))->getProcess();
+
+    $helper->run($output, $process);
+
+Customized Display
+------------------
+
+You can display a customized error message using the third argument of the
+:method:`Symfony\\Component\\Console\\Helper\\ProcessHelper::run` method::
+
+    $helper->run($output, $process, 'The process failed :(');
+
+A custom process callback can be passed as fourth argument, refer to the
+:doc:`Process Component </components/process>` for callback documentation::
+
+    use Symfony\Component\Process\Process;
+
+    $helper->run($output, $process, 'The process failed :(', function ($type, $data) {
+        if (Process::ERR === $type) {
+            // ... do something with the stderr output
+        } else {
+            // ... do something with the stdout
+        }
+    });