Skip to content

[Console] Enhance MarkdownDescriptor #20896

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 3 commits into from
Feb 16, 2017
Merged

[Console] Enhance MarkdownDescriptor #20896

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fc2395e
[Console] MarkdownDescriptor: Link to commands anchors
ogizanagi Dec 13, 2016
6896865
[Console] MarkdownDescriptor: Don't use getLongVersion
ogizanagi Dec 13, 2016
ef5b087
Do not output formatting tags
ogizanagi Dec 26, 2016
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
42 changes: 39 additions & 3 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 @@ -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.
Expand All @@ -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)
Copy link
Contributor Author

@ogizanagi ogizanagi Dec 26, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't know if it's something acceptable to change the default value of an argument ($decorated) when overriding a method for such case.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Default makes sense i guess. Is it really worth against changing write calls?

{
parent::write($content, $decorated);
}

/**
* {@inheritdoc}
*/
Expand Down Expand Up @@ -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']) {
Expand All @@ -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'])));
}

Expand All @@ -143,4 +166,17 @@ protected function describeApplication(Application $application, array $options
$this->write($this->describeCommand($command));
}
}

private function getApplicationTitle(Application $application)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we do a new method i'd say ApplicationDescription::getTitle for better reuseability.

{
if ('UNKNOWN' !== $application->getName()) {
if ('UNKNOWN' !== $application->getVersion()) {
return sprintf('%s %s', $application->getName(), $application->getVersion());
}

return $application->getName();
}

return 'Console Tool';
}
}
26 changes: 13 additions & 13 deletions src/Symfony/Component/Console/Tests/Fixtures/application_1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
Console Tool
============

* `help`
* `list`
* [`help`](#help)
* [`list`](#list)

`help`
------
Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down
38 changes: 19 additions & 19 deletions src/Symfony/Component/Console/Tests/Fixtures/application_2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`
------
Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down
28 changes: 14 additions & 14 deletions src/Symfony/Component/Console/Tests/Fixtures/application_mbstring.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
MbString åpplicätion
====================

* `help`
* `list`
* [`help`](#help)
* [`list`](#list)

**descriptor:**

* `descriptor:åèä`
* [`descriptor:åèä`](#descriptoråèä)

`help`
------
Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion src/Symfony/Component/Console/Tests/Fixtures/input_argument_with_style.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,4 @@ argument description

* Is required: no
* Is array: no
* Default: `'<comment>style</>'`
* Default: `'style'`
2 changes: 1 addition & 1 deletion src/Symfony/Component/Console/Tests/Fixtures/input_option_with_style.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@ option description
* Accept value: yes
* Is value required: yes
* Is multiple: no
* Default: `'<comment>style</>'`
* Default: `'style'`
2 changes: 1 addition & 1 deletion src/Symfony/Component/Console/Tests/Fixtures/input_option_with_style_array.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',)`