feature symfony#20866 [Console] Improve markdown format (ro0NL)

This PR was merged into the 3.3-dev branch.

Discussion
----------

[Console] Improve markdown format

| Q             | A
| ------------- | ---
| Branch?       | "master"
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | not sure?
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | comma-separated list of tickets fixed by the PR, if any
| License       | MIT
| Doc PR        | reference to the documentation PR, if any

This improves the markdown description for a console application. To make the ouput read more friendly and intuitively (less bloated IMHO).

Before:

Markdown files in https://github.com/symfony/symfony/tree/master/src/Symfony/Component/Console/Tests/Fixtures

After:

Markdown files in https://github.com/ro0NL/symfony/tree/console/markdown/src/Symfony/Component/Console/Tests/Fixtures

Commits
-------

302a19d [Console] Improve markdown format

Author: fabpot

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

@@ -32,11 +32,10 @@ class MarkdownDescriptor extends Descriptor
     protected function describeInputArgument(InputArgument $argument, array $options = array())
     {
         $this->write(
-            '**'.$argument->getName().':**'."\n\n"
-            .'* Name: '.($argument->getName() ?: '<none>')."\n"
+            '#### `'.($argument->getName() ?: '<none>')."`\n\n"
+            .($argument->getDescription() ? preg_replace('/\s*[\r\n]\s*/', "\n", $argument->getDescription())."\n\n" : '')
             .'* Is required: '.($argument->isRequired() ? 'yes' : 'no')."\n"
             .'* Is array: '.($argument->isArray() ? 'yes' : 'no')."\n"
-            .'* Description: '.preg_replace('/\s*[\r\n]\s*/', "\n  ", $argument->getDescription() ?: '<none>')."\n"
             .'* Default: `'.str_replace("\n", '', var_export($argument->getDefault(), true)).'`'
         );
     }
@@ -46,14 +45,17 @@ protected function describeInputArgument(InputArgument $argument, array $options
      */
     protected function describeInputOption(InputOption $option, array $options = array())
     {
+        $name = '--'.$option->getName();
+        if ($option->getShortcut()) {
+            $name .= '|-'.implode('|-', explode('|', $option->getShortcut())).'';
+        }
+
         $this->write(
-            '**'.$option->getName().':**'."\n\n"
-            .'* Name: `--'.$option->getName().'`'."\n"
-            .'* Shortcut: '.($option->getShortcut() ? '`-'.implode('|-', explode('|', $option->getShortcut())).'`' : '<none>')."\n"
+            '#### `'.$name.'`'."\n\n"
+            .($option->getDescription() ? preg_replace('/\s*[\r\n]\s*/', "\n", $option->getDescription())."\n\n" : '')
             .'* Accept value: '.($option->acceptValue() ? 'yes' : 'no')."\n"
             .'* Is value required: '.($option->isValueRequired() ? 'yes' : 'no')."\n"
             .'* Is multiple: '.($option->isArray() ? 'yes' : 'no')."\n"
-            .'* Description: '.preg_replace('/\s*[\r\n]\s*/', "\n  ", $option->getDescription() ?: '<none>')."\n"
             .'* Default: `'.str_replace("\n", '', var_export($option->getDefault(), true)).'`'
         );
     }
@@ -64,7 +66,7 @@ protected function describeInputOption(InputOption $option, array $options = arr
     protected function describeInputDefinition(InputDefinition $definition, array $options = array())
     {
         if ($showArguments = count($definition->getArguments()) > 0) {
-            $this->write('### Arguments:');
+            $this->write('### Arguments');
             foreach ($definition->getArguments() as $argument) {
                 $this->write("\n\n");
                 $this->write($this->describeInputArgument($argument));
@@ -76,7 +78,7 @@ protected function describeInputDefinition(InputDefinition $definition, array $o
                 $this->write("\n\n");
             }
 
-            $this->write('### Options:');
+            $this->write('### Options');
             foreach ($definition->getOptions() as $option) {
                 $this->write("\n\n");
                 $this->write($this->describeInputOption($option));
@@ -93,12 +95,12 @@ protected function describeCommand(Command $command, array $options = array())
         $command->mergeApplicationDefinition(false);
 
         $this->write(
-            $command->getName()."\n"
-            .str_repeat('-', strlen($command->getName()))."\n\n"
-            .'* Description: '.($command->getDescription() ?: '<none>')."\n"
-            .'* Usage:'."\n\n"
+            '`'.$command->getName()."`\n"
+            .str_repeat('-', strlen($command->getName()) + 2)."\n\n"
+            .($command->getDescription() ? $command->getDescription()."\n\n" : '')
+            .'### Usage'."\n\n"
             .array_reduce(array_merge(array($command->getSynopsis()), $command->getAliases(), $command->getUsages()), function ($carry, $usage) {
-                return $carry.'  * `'.$usage.'`'."\n";
+                return $carry.'* `'.$usage.'`'."\n";
             })
         );
 
@@ -121,7 +123,7 @@ protected function describeApplication(Application $application, array $options
         $describedNamespace = isset($options['namespace']) ? $options['namespace'] : null;
         $description = new ApplicationDescription($application, $describedNamespace);
 
-        $this->write($application->getName()."\n".str_repeat('=', strlen($application->getName())));
+        $this->write($application->getLongVersion()."\n".str_repeat('=', strlen($application->getLongVersion())));
 
         foreach ($description->getNamespaces() as $namespace) {
             if (ApplicationDescription::GLOBAL_NAMESPACE !== $namespace['id']) {
@@ -131,7 +133,7 @@ protected function describeApplication(Application $application, array $options
 
             $this->write("\n\n");
             $this->write(implode("\n", array_map(function ($commandName) {
-                return '* '.$commandName;
+                return '* `'.$commandName.'`';
             }, $namespace['commands'])));
         }
 

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

@@ -1,16 +1,17 @@
-UNKNOWN
-=======
+Console Tool
+============
 
-* help
-* list
+* `help`
+* `list`
 
-help
-----
+`help`
+------
 
-* Description: Displays help for a command
-* Usage:
+Displays help for a command
 
-  * `help [--format FORMAT] [--raw] [--] [<command_name>]`
+### Usage
+
+* `help [--format FORMAT] [--raw] [--] [<command_name>]`
 
 The <info>help</info> command displays help for a given command:
 
@@ -22,115 +23,107 @@ You can also output the help in other formats by using the <comment>--format</co
 
 To display the list of available commands, please use the <info>list</info> command.
 
-### Arguments:
+### Arguments
+
+#### `command_name`
 
-**command_name:**
+The command name
 
-* Name: command_name
 * Is required: no
 * Is array: no
-* Description: The command name
 * Default: `'help'`
 
-### Options:
+### Options
 
-**format:**
+#### `--format`
+
+The output format (txt, xml, json, or md)
 
-* Name: `--format`
-* Shortcut: <none>
 * Accept value: yes
 * Is value required: yes
 * Is multiple: no
-* Description: The output format (txt, xml, json, or md)
 * Default: `'txt'`
 
-**raw:**
+#### `--raw`
+
+To output raw command help
 
-* Name: `--raw`
-* Shortcut: <none>
 * Accept value: no
 * Is value required: no
 * Is multiple: no
-* Description: To output raw command help
 * Default: `false`
 
-**help:**
+#### `--help|-h`
+
+Display this help message
 
-* Name: `--help`
-* Shortcut: `-h`
 * Accept value: no
 * Is value required: no
 * Is multiple: no
-* Description: Display this help message
 * Default: `false`
 
-**quiet:**
+#### `--quiet|-q`
+
+Do not output any message
 
-* Name: `--quiet`
-* Shortcut: `-q`
 * Accept value: no
 * Is value required: no
 * Is multiple: no
-* Description: Do not output any message
 * Default: `false`
 
-**verbose:**
+#### `--verbose|-v|-vv|-vvv`
+
+Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
 
-* Name: `--verbose`
-* Shortcut: `-v|-vv|-vvv`
 * Accept value: no
 * Is value required: no
 * Is multiple: no
-* Description: Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
 * Default: `false`
 
-**version:**
+#### `--version|-V`
+
+Display this application version
 
-* Name: `--version`
-* Shortcut: `-V`
 * Accept value: no
 * Is value required: no
 * Is multiple: no
-* Description: Display this application version
 * Default: `false`
 
-**ansi:**
+#### `--ansi`
+
+Force ANSI output
 
-* Name: `--ansi`
-* Shortcut: <none>
 * Accept value: no
 * Is value required: no
 * Is multiple: no
-* Description: Force ANSI output
 * Default: `false`
 
-**no-ansi:**
+#### `--no-ansi`
+
+Disable ANSI output
 
-* Name: `--no-ansi`
-* Shortcut: <none>
 * Accept value: no
 * Is value required: no
 * Is multiple: no
-* Description: Disable ANSI output
 * Default: `false`
 
-**no-interaction:**
+#### `--no-interaction|-n`
+
+Do not ask any interactive question
 
-* Name: `--no-interaction`
-* Shortcut: `-n`
 * Accept value: no
 * Is value required: no
 * Is multiple: no
-* Description: Do not ask any interactive question
 * Default: `false`
 
-list
-----
+`list`
+------
+
+Lists commands
 
-* Description: Lists commands
-* Usage:
+### Usage
 
-  * `list [--raw] [--format FORMAT] [--] [<namespace>]`
+* `list [--raw] [--format FORMAT] [--] [<namespace>]`
 
 The <info>list</info> command lists all commands:
 
@@ -148,34 +141,32 @@ It's also possible to get raw list of commands (useful for embedding command run
 
   <info>php app/console list --raw</info>
 
-### Arguments:
+### Arguments
 
-**namespace:**
+#### `namespace`
+
+The namespace name
 
-* Name: namespace
 * Is required: no
 * Is array: no
-* Description: The namespace name
 * Default: `NULL`
 
-### Options:
+### Options
+
+#### `--raw`
 
-**raw:**
+To output raw command list
 
-* Name: `--raw`
-* Shortcut: <none>
 * Accept value: no
 * Is value required: no
 * Is multiple: no
-* Description: To output raw command list
 * Default: `false`
 
-**format:**
+#### `--format`
+
+The output format (txt, xml, json, or md)
 
-* Name: `--format`
-* Shortcut: <none>
 * Accept value: yes
 * Is value required: yes
 * Is multiple: no
-* Description: The output format (txt, xml, json, or md)
 * Default: `'txt'`