minor #20896 [Console] Enhance MarkdownDescriptor (ogizanagi)

This PR was squashed before being merged into the 3.3-dev branch (closes #20896).

Discussion
----------

[Console] Enhance MarkdownDescriptor

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | yes
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | N/A
| License       | MIT
| Doc PR        | N/A

In order to add usefulness to this descriptor, this PR allows to jump to a command description by clicking on the command name on the application summary.

It's not a generic approach but IMHO a quick win that should work at least for Github flavoured markdown.

The markdown format should also avoid using `Application::getLongVersion` as the markdown document title, as it may contain tags (and unnecessary information using the framework).

Lastly, the markdown format is now cleaned from tags initially used for console output formatting and only keeps properly escaped ones.

Commits
-------

ef5b087 Do not output formatting tags
6896865 [Console] MarkdownDescriptor: Don't use getLongVersion
fc2395e [Console] MarkdownDescriptor: Link to commands anchors

src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php

@@ -17,6 +17,7 @@
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputDefinition;
 use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
 
 /**
  * Markdown descriptor.
@@ -27,6 +28,27 @@
  */
 class MarkdownDescriptor extends Descriptor
 {
+    /**
+     * {@inheritdoc}
+     */
+    public function describe(OutputInterface $output, $object, array $options = array())
+    {
+        $decorated = $output->isDecorated();
+        $output->setDecorated(false);
+
+        parent::describe($output, $object, $options);
+
+        $output->setDecorated($decorated);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function write($content, $decorated = true)
+    {
+        parent::write($content, $decorated);
+    }
+
     /**
      * {@inheritdoc}
      */
@@ -123,8 +145,9 @@ protected function describeApplication(Application $application, array $options
     {
         $describedNamespace = isset($options['namespace']) ? $options['namespace'] : null;
         $description = new ApplicationDescription($application, $describedNamespace);
+        $title = $this->getApplicationTitle($application);
 
-        $this->write($application->getLongVersion()."\n".str_repeat('=', Helper::strlen($application->getLongVersion())));
+        $this->write($title."\n".str_repeat('=', Helper::strlen($title)));
 
         foreach ($description->getNamespaces() as $namespace) {
             if (ApplicationDescription::GLOBAL_NAMESPACE !== $namespace['id']) {
@@ -133,8 +156,8 @@ protected function describeApplication(Application $application, array $options
             }
 
             $this->write("\n\n");
-            $this->write(implode("\n", array_map(function ($commandName) {
-                return '* `'.$commandName.'`';
+            $this->write(implode("\n", array_map(function ($commandName) use ($description) {
+                return sprintf('* [`%s`](#%s)', $commandName, str_replace(':', '', $description->getCommand($commandName)->getName()));
             }, $namespace['commands'])));
         }
 
@@ -143,4 +166,17 @@ protected function describeApplication(Application $application, array $options
             $this->write($this->describeCommand($command));
         }
     }
+
+    private function getApplicationTitle(Application $application)
+    {
+        if ('UNKNOWN' !== $application->getName()) {
+            if ('UNKNOWN' !== $application->getVersion()) {
+                return sprintf('%s %s', $application->getName(), $application->getVersion());
+            }
+
+            return $application->getName();
+        }
+
+        return 'Console Tool';
+    }
 }

src/Symfony/Component/Console/Tests/Fixtures/application_1.md

@@ -1,8 +1,8 @@
 Console Tool
 ============
 
-* `help`
-* `list`
+* [`help`](#help)
+* [`list`](#list)
 
 `help`
 ------
@@ -13,15 +13,15 @@ Displays help for a command
 
 * `help [--format FORMAT] [--raw] [--] [<command_name>]`
 
-The <info>help</info> command displays help for a given command:
+The help command displays help for a given command:
 
-  <info>php app/console help list</info>
+  php app/console help list
 
-You can also output the help in other formats by using the <comment>--format</comment> option:
+You can also output the help in other formats by using the --format option:
 
-  <info>php app/console help --format=xml list</info>
+  php app/console help --format=xml list
 
-To display the list of available commands, please use the <info>list</info> command.
+To display the list of available commands, please use the list command.
 
 ### Arguments
 
@@ -125,21 +125,21 @@ Lists commands
 
 * `list [--raw] [--format FORMAT] [--] [<namespace>]`
 
-The <info>list</info> command lists all commands:
+The list command lists all commands:
 
-  <info>php app/console list</info>
+  php app/console list
 
 You can also display the commands for a specific namespace:
 
-  <info>php app/console list test</info>
+  php app/console list test
 
-You can also output the information in other formats by using the <comment>--format</comment> option:
+You can also output the information in other formats by using the --format option:
 
-  <info>php app/console list --format=xml</info>
+  php app/console list --format=xml
 
 It's also possible to get raw list of commands (useful for embedding command runner):
 
-  <info>php app/console list --raw</info>
+  php app/console list --raw
 
 ### Arguments
 

src/Symfony/Component/Console/Tests/Fixtures/application_2.md

@@ -1,15 +1,15 @@
-My Symfony application <info>v1.0</info>
-========================================
+My Symfony application v1.0
+===========================
 
-* `alias1`
-* `alias2`
-* `help`
-* `list`
+* [`alias1`](#descriptorcommand1)
+* [`alias2`](#descriptorcommand1)
+* [`help`](#help)
+* [`list`](#list)
 
 **descriptor:**
 
-* `descriptor:command1`
-* `descriptor:command2`
+* [`descriptor:command1`](#descriptorcommand1)
+* [`descriptor:command2`](#descriptorcommand2)
 
 `help`
 ------
@@ -20,15 +20,15 @@ Displays help for a command
 
 * `help [--format FORMAT] [--raw] [--] [<command_name>]`
 
-The <info>help</info> command displays help for a given command:
+The help command displays help for a given command:
 
-  <info>php app/console help list</info>
+  php app/console help list
 
-You can also output the help in other formats by using the <comment>--format</comment> option:
+You can also output the help in other formats by using the --format option:
 
-  <info>php app/console help --format=xml list</info>
+  php app/console help --format=xml list
 
-To display the list of available commands, please use the <info>list</info> command.
+To display the list of available commands, please use the list command.
 
 ### Arguments
 
@@ -132,21 +132,21 @@ Lists commands
 
 * `list [--raw] [--format FORMAT] [--] [<namespace>]`
 
-The <info>list</info> command lists all commands:
+The list command lists all commands:
 
-  <info>php app/console list</info>
+  php app/console list
 
 You can also display the commands for a specific namespace:
 
-  <info>php app/console list test</info>
+  php app/console list test
 
-You can also output the information in other formats by using the <comment>--format</comment> option:
+You can also output the information in other formats by using the --format option:
 
-  <info>php app/console list --format=xml</info>
+  php app/console list --format=xml
 
 It's also possible to get raw list of commands (useful for embedding command runner):
 
-  <info>php app/console list --raw</info>
+  php app/console list --raw
 
 ### Arguments
 

src/Symfony/Component/Console/Tests/Fixtures/application_mbstring.md

@@ -1,12 +1,12 @@
 MbString åpplicätion
 ====================
 
-* `help`
-* `list`
+* [`help`](#help)
+* [`list`](#list)
 
 **descriptor:**
 
-* `descriptor:åèä`
+* [`descriptor:åèä`](#descriptoråèä)
 
 `help`
 ------
@@ -17,15 +17,15 @@ Displays help for a command
 
 * `help [--format FORMAT] [--raw] [--] [<command_name>]`
 
-The <info>help</info> command displays help for a given command:
+The help command displays help for a given command:
 
-  <info>php app/console help list</info>
+  php app/console help list
 
-You can also output the help in other formats by using the <comment>--format</comment> option:
+You can also output the help in other formats by using the --format option:
 
-  <info>php app/console help --format=xml list</info>
+  php app/console help --format=xml list
 
-To display the list of available commands, please use the <info>list</info> command.
+To display the list of available commands, please use the list command.
 
 ### Arguments
 
@@ -129,21 +129,21 @@ Lists commands
 
 * `list [--raw] [--format FORMAT] [--] [<namespace>]`
 
-The <info>list</info> command lists all commands:
+The list command lists all commands:
 
-  <info>php app/console list</info>
+  php app/console list
 
 You can also display the commands for a specific namespace:
 
-  <info>php app/console list test</info>
+  php app/console list test
 
-You can also output the information in other formats by using the <comment>--format</comment> option:
+You can also output the information in other formats by using the --format option:
 
-  <info>php app/console list --format=xml</info>
+  php app/console list --format=xml
 
 It's also possible to get raw list of commands (useful for embedding command runner):
 
-  <info>php app/console list --raw</info>
+  php app/console list --raw
 
 ### Arguments
 

src/Symfony/Component/Console/Tests/Fixtures/input_argument_with_style.md

@@ -4,4 +4,4 @@ argument description
 
 * Is required: no
 * Is array: no
-* Default: `'<comment>style</>'`
+* Default: `'style'`

src/Symfony/Component/Console/Tests/Fixtures/input_option_with_style.md

@@ -5,4 +5,4 @@ option description
 * Accept value: yes
 * Is value required: yes
 * Is multiple: no
-* Default: `'<comment>style</>'`
+* Default: `'style'`

src/Symfony/Component/Console/Tests/Fixtures/input_option_with_style_array.md

@@ -5,4 +5,4 @@ option description
 * Accept value: yes
 * Is value required: yes
 * Is multiple: yes
-* Default: `array (  0 => '<comment>Hello</comment>',  1 => '<info>world</info>',)`
+* Default: `array (  0 => 'Hello',  1 => 'world',)`