Move Calling other commands to a guide article

Author: wouterj

components/console.rst

@@ -192,68 +192,6 @@ method::
     You can also test a whole console application by using
     :class:`Symfony\\Component\\Console\\Tester\\ApplicationTester`.
 
-.. _calling-existing-command:
-
-Calling an Existing Command
----------------------------
-
-If a command depends on another one being run before it, instead of asking the
-user to remember the order of execution, you can call it directly yourself.
-This is also useful if you want to create a "meta" command that just runs a
-bunch of other commands (for instance, all commands that need to be run when
-the project's code has changed on the production servers: clearing the cache,
-generating Doctrine2 proxies, dumping Assetic assets, ...).
-
-Calling a command from another one is straightforward::
-
-    protected function execute(InputInterface $input, OutputInterface $output)
-    {
-        $command = $this->getApplication()->find('demo:greet');
-
-        $arguments = array(
-            'command' => 'demo:greet',
-            'name'    => 'Fabien',
-            '--yell'  => true,
-        );
-
-        $greetInput = new ArrayInput($arguments);
-        $returnCode = $command->run($greetInput, $output);
-
-        // ...
-    }
-
-First, you :method:`Symfony\\Component\\Console\\Application::find` the
-command you want to execute by passing the command name. Then, you need to create
-a new :class:`Symfony\\Component\\Console\\Input\\ArrayInput` with the arguments
-and options you want to pass to the command.
-
-Eventually, calling the ``run()`` method actually executes the command and
-returns the returned code from the command (return value from command's
-``execute()`` method).
-
-.. tip::
-
-    If you want to suppress the output of the executed command, pass a
-    :class:`Symfony\\Component\\Console\\Output\\NullOutput` as the second
-    argument to ``$command->run()``.
-
-.. caution::
-
-    Note that all the commands will run in the same process and some of Symfony's
-    built-in commands may not work well this way. For instance, the ``cache:clear``
-    and ``cache:warmup`` commands change some class definitions, so running
-    something after them is likely to break.
-
-.. note::
-
-    Most of the time, calling a command from code that is not executed on the
-    command line is not a good idea for several reasons. First, the command's
-    output is optimized for the console. But more important, you can think of
-    a command as being like a controller; it should use the model to do
-    something and display feedback to the user. So, instead of calling a
-    command from the Web, refactor your code and move the logic to a new
-    class.
-
 Learn More
 ----------
 

console.rst

@@ -220,12 +220,6 @@ command:
     This method is executed after ``interact()`` and ``initialize()``.
     It contains the logic you want the command to execute.
 
-Invoking other Commands
------------------------
-
-See :ref:`calling-existing-command` if you need to implement a command that runs
-other dependent commands.
-
 Testing Commands
 ----------------
 

console/calling_commands.rst

@@ -0,0 +1,59 @@
+How to Call Other Commands
+==========================
+
+If a command depends on another one being run before it, instead of asking the
+user to remember the order of execution, you can call it directly yourself.
+This is also useful if you want to create a "meta" command that just runs a
+bunch of other commands (for instance, all commands that need to be run when
+the project's code has changed on the production servers: clearing the cache,
+generating Doctrine2 proxies, dumping Assetic assets, ...).
+
+Calling a command from another one is straightforward::
+
+    protected function execute(InputInterface $input, OutputInterface $output)
+    {
+        $command = $this->getApplication()->find('demo:greet');
+
+        $arguments = array(
+            'command' => 'demo:greet',
+            'name'    => 'Fabien',
+            '--yell'  => true,
+        );
+
+        $greetInput = new ArrayInput($arguments);
+        $returnCode = $command->run($greetInput, $output);
+
+        // ...
+    }
+
+First, you :method:`Symfony\\Component\\Console\\Application::find` the
+command you want to execute by passing the command name. Then, you need to create
+a new :class:`Symfony\\Component\\Console\\Input\\ArrayInput` with the arguments
+and options you want to pass to the command.
+
+Eventually, calling the ``run()`` method actually executes the command and
+returns the returned code from the command (return value from command's
+``execute()`` method).
+
+.. tip::
+
+    If you want to suppress the output of the executed command, pass a
+    :class:`Symfony\\Component\\Console\\Output\\NullOutput` as the second
+    argument to ``$command->run()``.
+
+.. caution::
+
+    Note that all the commands will run in the same process and some of Symfony's
+    built-in commands may not work well this way. For instance, the ``cache:clear``
+    and ``cache:warmup`` commands change some class definitions, so running
+    something after them is likely to break.
+
+.. note::
+
+    Most of the time, calling a command from code that is not executed on the
+    command line is not a good idea for several reasons. First, the command's
+    output is optimized for the console. But more important, you can think of
+    a command as being like a controller; it should use the model to do
+    something and display feedback to the user. So, instead of calling a
+    command from the Web, refactor your code and move the logic to a new
+    class.