8000 [Console] Improve markdown format by ro0NL · Pull Request #20866 · symfony/symfony · GitHub
[go: up one dir, main page]
Skip to content

[Console] Improve markdown format #20866

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 13, 2016
Merged

[Console] Improve markdown format #20866

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 18 additions & 16 deletions src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)).'`'
);
}
Expand All @@ -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)).'`'
);
}
Expand All @@ -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));
Expand All @@ -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));
Expand All @@ -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" 10000
.($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";
})
);

Expand All @@ -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']) {
Expand All @@ -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'])));
}

Expand Down
127 changes: 59 additions & 68 deletions src/Symfony/Component/Console/Tests/Fixtures/application_1.md
View file
Open in desktop
10000
Original file line number Diff line number Diff line change
@@ -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:

Expand All @@ -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:

Expand All @@ -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'`
Loading
0