diogo/symfony
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[Console] Improve markdown format

Browse Source
This commit is contained in:
Roland Franssen 2016-12-11 11:31:10 +00:00
parent 51bc35cc84
commit 302a19d779
18 changed files with 259 additions and 315 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php
View File

@ -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 @@ class MarkdownDescriptor extends Descriptor
*/
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 @@ class MarkdownDescriptor extends Descriptor
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 @@ class MarkdownDescriptor extends Descriptor
$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 @@ class MarkdownDescriptor extends Descriptor
$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 @@ class MarkdownDescriptor extends Descriptor
$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 @@ class MarkdownDescriptor extends Descriptor
$this->write("\n\n");
$this->write(implode("\n", array_map(function ($commandName) {
return '* '.$commandName;
return '* `'.$commandName.'`';
}, $namespace['commands'])));
}

127
src/Symfony/Component/Console/Tests/Fixtures/application_1.md
View File

@ -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`
------
* Description: Lists commands
* Usage:
Lists commands
* `list [--raw] [--format FORMAT] [--] [<namespace>]`
### Usage
* `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'`

278
src/Symfony/Component/Console/Tests/Fixtures/application_2.md
View File

@ -1,23 +1,24 @@
My Symfony application
======================
My Symfony application <info>v1.0</info>
========================================
* alias1
* alias2
* help
* list
* `alias1`
* `alias2`
* `help`
* `list`
**descriptor:**
* descriptor:command1
* descriptor:command2
* `descriptor:command1`
* `descriptor:command2`
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:
@ -29,115 +30,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`
------
* Description: Lists commands
* Usage:
Lists commands
* `list [--raw] [--format FORMAT] [--] [<namespace>]`
### Usage
* `list [--raw] [--format FORMAT] [--] [<namespace>]`
The <info>list</info> command lists all commands:
@ -155,222 +148,203 @@ 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'`
descriptor:command1
-------------------
`descriptor:command1`
---------------------
* Description: command 1 description
* Usage:
command 1 description
* `descriptor:command1`
* `alias1`
* `alias2`
### Usage
* `descriptor:command1`
* `alias1`
* `alias2`
command 1 help
### Options:
### Options
**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`
descriptor:command2
-------------------
`descriptor:command2`
---------------------
* Description: command 2 description
* Usage:
command 2 description
* `descriptor:command2 [-o|--option_name] [--] <argument_name>`
* `descriptor:command2 -o|--option_name <argument_name>`
* `descriptor:command2 <argument_name>`
### Usage
* `descriptor:command2 [-o|--option_name] [--] <argument_name>`
* `descriptor:command2 -o|--option_name <argument_name>`
* `descriptor:command2 <argument_name>`
command 2 help
### Arguments:
### Arguments
**argument_name:**
#### `argument_name`
* Name: argument_name
* Is required: yes
* Is array: no
* Description: <none>
* Default: `NULL`
### Options:
### Options
**option_name:**
#### `--option_name|-o`
* Name: `--option_name`
* Shortcut: `-o`
* Accept value: no
* Is value required: no
* Is multiple: no
* Description: <none>
* 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`

15
src/Symfony/Component/Console/Tests/Fixtures/command_1.md
View File

@ -1,11 +1,12 @@
descriptor:command1
-------------------
`descriptor:command1`
---------------------
* Description: command 1 description
* Usage:
command 1 description
* `descriptor:command1`
* `alias1`
* `alias2`
### Usage
* `descriptor:command1`
* `alias1`
* `alias2`
command 1 help

28
src/Symfony/Component/Console/Tests/Fixtures/command_2.md
View File

@ -1,33 +1,29 @@
descriptor:command2
-------------------
`descriptor:command2`
---------------------
* Description: command 2 description
* Usage:
command 2 description
* `descriptor:command2 [-o|--option_name] [--] <argument_name>`
* `descriptor:command2 -o|--option_name <argument_name>`
* `descriptor:command2 <argument_name>`
### Usage
* `descriptor:command2 [-o|--option_name] [--] <argument_name>`
* `descriptor:command2 -o|--option_name <argument_name>`
* `descriptor:command2 <argument_name>`
command 2 help
### Arguments:
### Arguments
**argument_name:**
#### `argument_name`
* Name: argument_name
* Is required: yes
* Is array: no
* Description: <none>
* Default: `NULL`
### Options:
### Options
**option_name:**
#### `--option_name|-o`
* Name: `--option_name`
* Shortcut: `-o`
* Accept value: no
* Is value required: no
* Is multiple: no
* Description: <none>
* Default: `false`

4
src/Symfony/Component/Console/Tests/Fixtures/input_argument_1.md
View File

@ -1,7 +1,5 @@
**argument_name:**
#### `argument_name`
* Name: argument_name
* Is required: yes
* Is array: no
* Description: <none>
* Default: `NULL`

6
src/Symfony/Component/Console/Tests/Fixtures/input_argument_2.md
View File

@ -1,7 +1,7 @@
**argument_name:**
#### `argument_name`
argument description
* Name: argument_name
* Is required: no
* Is array: yes
* Description: argument description
* Default: `array ()`

6
src/Symfony/Component/Console/Tests/Fixtures/input_argument_3.md
View File

@ -1,7 +1,7 @@
**argument_name:**
#### `argument_name`
argument description
* Name: argument_name
* Is required: no
* Is array: no
* Description: argument description
* Default: `'default_value'`

8
src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.md
View File

@ -1,8 +1,8 @@
**argument_name:**
#### `argument_name`
multiline
argument description
* Name: argument_name
* Is required: yes
* Is array: no
* Description: multiline
argument description
* Default: `NULL`

6
src/Symfony/Component/Console/Tests/Fixtures/input_definition_2.md
View File

@ -1,9 +1,7 @@
### Arguments:
### Arguments
**argument_name:**
#### `argument_name`
* Name: argument_name
* Is required: yes
* Is array: no
* Description: <none>
* Default: `NULL`

7
src/Symfony/Component/Console/Tests/Fixtures/input_definition_3.md
View File

@ -1,11 +1,8 @@
### Options:
### Options
**option_name:**
#### `--option_name|-o`
* Name: `--option_name`
* Shortcut: `-o`
* Accept value: no
* Is value required: no
* Is multiple: no
* Description: <none>
* Default: `false`

13
src/Symfony/Component/Console/Tests/Fixtures/input_definition_4.md
View File

@ -1,21 +1,16 @@
### Arguments:
### Arguments
**argument_name:**
#### `argument_name`
* Name: argument_name
* Is required: yes
* Is array: no
* Description: <none>
* Default: `NULL`
### Options:
### Options
**option_name:**
#### `--option_name|-o`
* Name: `--option_name`
* Shortcut: `-o`
* Accept value: no
* Is value required: no
* Is multiple: no
* Description: <none>
* Default: `false`

5
src/Symfony/Component/Console/Tests/Fixtures/input_option_1.md
View File

@ -1,9 +1,6 @@
**option_name:**
#### `--option_name|-o`
* Name: `--option_name`
* Shortcut: `-o`
* Accept value: no
* Is value required: no
* Is multiple: no
* Description: <none>
* Default: `false`

7
src/Symfony/Component/Console/Tests/Fixtures/input_option_2.md
View File

@ -1,9 +1,8 @@
**option_name:**
#### `--option_name|-o`
option description
* Name: `--option_name`
* Shortcut: `-o`
* Accept value: yes
* Is value required: no
* Is multiple: no
* Description: option description
* Default: `'default_value'`

7
src/Symfony/Component/Console/Tests/Fixtures/input_option_3.md
View File

@ -1,9 +1,8 @@
**option_name:**
#### `--option_name|-o`
option description
* Name: `--option_name`
* Shortcut: `-o`
* Accept value: yes
* Is value required: yes
* Is multiple: no
* Description: option description
* Default: `NULL`

7
src/Symfony/Component/Console/Tests/Fixtures/input_option_4.md
View File

@ -1,9 +1,8 @@
**option_name:**
#### `--option_name|-o`
option description
* Name: `--option_name`
* Shortcut: `-o`
* Accept value: yes
* Is value required: no
* Is multiple: yes
* Description: option description
* Default: `array ()`

9
src/Symfony/Component/Console/Tests/Fixtures/input_option_5.md
View File

@ -1,10 +1,9 @@
**option_name:**
#### `--option_name|-o`
multiline
option description
* Name: `--option_name`
* Shortcut: `-o`
* Accept value: yes
* Is value required: yes
* Is multiple: no
* Description: multiline
option description
* Default: `NULL`

7
src/Symfony/Component/Console/Tests/Fixtures/input_option_6.md
View File

@ -1,9 +1,8 @@
**option_name:**
#### `--option_name|-o|-O`
option with multiple shortcuts
* Name: `--option_name`
* Shortcut: `-o|-O`
* Accept value: yes
* Is value required: yes
* Is multiple: no
* Description: option with multiple shortcuts
* Default: `NULL`