8000 Add ReStructuredText descriptor for console component. by grasmash · Pull Request #45718 · symfony/symfony · GitHub
[go: up one dir, main page]
Skip to content

Add ReStructuredText descriptor for console component. #45718

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

Closed
wants to merge 12 commits into from
Closed

Add ReStructuredText descriptor for console component. #45718

Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
9990248
Add ReStructuredText descriptor for console component.
grasmash Mar 11, 2022
a3dd64a
Fix up.
grasmash Mar 11, 2022
3044d77
Add fixture placeholders.
grasmash Mar 11, 2022
ca7843a
Fix PHPCS issues.
grasmash Mar 11, 2022
ac5e84c
Add rst fixtures.
grasmash Mar 11, 2022
f0ba4f4
Fix fixtures.
grasmash Mar 11, 2022
f43d953
Fix string.
grasmash Mar 11, 2022
7d33e75
Fix paths.
grasmash Mar 11, 2022
9b76f9d
Add to helper.
grasmash Mar 11, 2022
a071663
Tests
grasmash Mar 11, 2022
728e356
Update fixtures again.
grasmash Mar 11, 2022
11c8f25
Last.
grasmash Mar 11, 2022
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
Prev Previous commit
Next Next commit
Fix PHPCS issues.
  • Loading branch information
@grasmash
grasmash committed Mar 11, 2022
commit ca7843a42d9a1bf5e2a6924e2b7bf34e82b7116b
268 changes: 136 additions & 132 deletions src/Symfony/Component/Console/Descriptor/ReStructuredTextDescriptor.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,10 @@
*/
class ReStructuredTextDescriptor extends Descriptor
{

private $applicationTitleUnderlineChar = '#';
private $commandTitleUnderlineChar = '*';
private $argumentsTitleUnderlineChar = '=';
private $argumentTitleUnderlineChar = '-';
private $applicationTitleUnderlineChar = '#';
Copy link
Member

Choose a reason for hiding this comment

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

Some context in case anyone needs it: RST format doesn't define which characters to use for <h1>, <h2>, <h3>, etc. RST defines a series of characters that you can use (###, ===, ^^^, ~~~, etc.) and the first one found is considered <h1>, the second set of characters found is considered <h2>, etc.

I'm not saying that we need to do the same here, but, for your consideration, the standard notation that we follow in Symfony Docs is:

h1 =====
h2 -----
h3 ~~~~~
h4 .....

Here we would be using:

h1 #####
h2 *****
h3 =====
h4 -----

private $commandTitleUnderlineChar = '*';
private $argumentsTitleUnderlineChar = '=';
private $argumentTitleUnderlineChar = '-';

/**
* {@inheritdoc}
Expand All @@ -52,155 +51,160 @@ protected function write(string $content, bool $decorated = true)
}

/**
* {@inheritdoc}
*/
protected function describeInputArgument(InputArgument $argument, array $options = []) {
$this->write(
'``' . ($argument->getName() ?: '<none>') . "``\n" . str_repeat($this->argumentTitleUnderlineChar, Helper::width($argument->getName()) + 4) . "\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"
. '- Default: ``' . str_replace("\n", '', var_export($argument->getDefault(), TRUE)) . '``'
* {@inheritdoc}
*/
protected function describeInputArgument(InputArgument $argument, array $options = [])
{
$this->write(
'``'.($argument->getName() ?: '<none>')."``\n".str_repeat($this->argumentTitleUnderlineChar, Helper::width($argument->getName()) + 4)."\n\n"
Copy link
Member

Choose a reason for hiding this comment

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

indentation looks wrong

.($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"
.'- Default: ``'.str_replace("\n", '', var_export($argument->getDefault(), true)).'``'
);
}

/**
* {@inheritdoc}
*/
protected function describeInputOption(InputOption $option, array $options = []) {
$name = '--' . $option->getName();
if ($option->isNegatable()) {
$name .= '|--no-' . $option->getName();
}
if ($option->getShortcut()) {
$name .= '|-' . str_replace('|', '|-', $option->getShortcut()) . '';
}

$this->write(
'``' . $name . '``' . "\n" . str_repeat($this->argumentTitleUnderlineChar, Helper::width($name) + 4) . "\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"
. '- Is negatable: ' . ($option->isNegatable() ? 'yes' : 'no') . "\n"
. '- Default: ``' . str_replace("\n", '', var_export($option->getDefault(), TRUE)) . '``'
);
}

/**
* {@inheritdoc}
*/
protected function describeInputDefinition(InputDefinition $definition, array $options = []) {
if ($showArguments = \count($definition->getArguments()) > 0) {
$this->write("Arguments\n" . str_repeat($this->argumentsTitleUnderlineChar, 9)) . "\n\n";
foreach ($definition->getArguments() as $argument) {
$this->write("\n\n");
if (NULL !== $describeInputArgument = $this->describeInputArgument($argument)) {
$this->write($describeInputArgument);
/**
* {@inheritdoc}
*/
protected function describeInputOption(InputOption $option, array $options = [])
{
$name = '--'.$option->getName();
if ($option->isNegatable()) {
$name .= '|--no-'.$option->getName();
}
if ($option->getShortcut()) {
$name .= '|-'.str_replace('|', '|-', $option->getShortcut()).'';
}
}

$this->write(
'``'.$name.'``'."\n".str_repeat($this->argumentTitleUnderlineChar, Helper::width($name) + 4)."\n\n"
Copy link
Member

Choose a reason for hiding this comment

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

here as well

.($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"
.'- Is negatable: '.($option->isNegatable() ? 'yes' : 'no')."\n"
.'- Default: ``'.str_replace("\n", '', var_export($option->getDefault(), true)).'``'
);
}

if (\count($definition->getOptions()) > 0) {
if ($showArguments) {
$this->write("\n\n");
}
/**
* {@inheritdoc}
*/
protected function describeInputDefinition(InputDefinition $definition, array $options = [])
{
if ($showArguments = \count($definition->getArguments()) > 0) {
$this->write("Arguments\n".str_repeat($this->argumentsTitleUnderlineChar, 9))."\n\n";
foreach ($definition->getArguments() as $argument) {
$this->write("\n\n");
if (null !== $describeInputArgument = $this->describeInputArgument($argument)) {
$this->write($describeInputArgument);
}
}
}

$this->write("Options\n" . str_repeat($this->argumentsTitleUnderlineChar, 7)) . "\n\n";
foreach ($definition->getOptions() as $option) {
$this->write("\n\n");
if (NULL !== $describeInputOption = $this->describeInputOption($option)) {
$this->write($describeInputOption);
if (\count($definition->getOptions()) > 0) {
if ($showArguments) {
$this->write("\n\n");
}

$this->write("Options\n".str_repeat($this->argumentsTitleUnderlineChar, 7))."\n\n";
foreach ($definition->getOptions() as $option) {
$this->write("\n\n");
if (null !== $describeInputOption = $this->describeInputOption($option)) {
$this->write($describeInputOption);
}
}
}
}
}
}

/**
* {@inheritdoc}
*/
protected function describeCommand(Command $command, array $options = []) {
if ($options['short'] ?? FALSE) {
$this->write(
'``' . $command->getName() . "``\n"
. str_repeat($this->commandTitleUnderlineChar, Helper::width($command->getName()) + 4) . "\n\n"
. ($command->getDescription() ? $command->getDescription() . "\n\n" : '')
. "Usage\n" . str_repeat($this->argumentsTitleUnderlineChar, 5) . "\n\n"
. array_reduce($command->getAliases(), function ($carry, $usage) {
return $carry . '- ``' . $usage . '``' . "\n";

/**
* {@inheritdoc}
*/
protected function describeCommand(Command $command, array $options = [])
{
if ($options['short'] ?? false) {
$this->write(
'``'.$command->getName()."``\n"
.str_repeat($this->commandTitleUnderlineChar, Helper::width($command->getName()) + 4)."\n\n"
.($command->getDescription() ? $command->getDescription()."\n\n" : '')
."Usage\n".str_repeat($this->argumentsTitleUnderlineChar, 5)."\n\n"
.array_reduce($command->getAliases(), function ($carry, $usage) {
return $carry.'- ``'.$usage.'``'."\n";
})
);

return;
}
return;
}

$command->mergeApplicationDefinition(FALSE);
$command->mergeApplicationDefinition(false);

foreach ($command->getAliases() as $alias) {
$this->write('.. _' . $alias . ":\n\n");
}
$this->write(
'``' . $command->getName() . "``\n"
. str_repeat($this->commandTitleUnderlineChar, Helper::width($command->getName()) + 4) . "\n\n"
. ($command->getDescription() ? $command->getDescription() . "\n\n" : '')
. "Usage\n" . str_repeat($this->argumentsTitleUnderlineChar, 5) . "\n\n"
. array_reduce(array_merge([$command->getSynopsis()], $command->getAliases(), $command->getUsages()), function ($carry, $usage) {
return $carry . '- ``' . $usage . '``' . "\n";
foreach ($command->getAliases() as $alias) {
$this->write('.. _'.$alias.":\n\n");
}
$this->write(
'``'.$command->getName()."``\n"
.str_repeat($this->commandTitleUnderlineChar, Helper::width($command->getName()) + 4)."\n\n"
.($command->getDescription() ? $command->getDescription()."\n\n" : '')
."Usage\n".str_repeat($this->argumentsTitleUnderlineChar, 5)."\n\n"
.array_reduce(array_merge([$command->getSynopsis()], $command->getAliases(), $command->getUsages()), function ($carry, $usage) {
return $carry.'- ``'.$usage.'``'."\n";
})
);

if ($help = $command->getProcessedHelp()) {
$this->write("\n");
$this->write($help);
}

$definition = $command->getDefinition();
if ($definition->getOptions() || $definition->getArguments()) {
$this->write("\n\n");
$this->describeInputDefinition($definition);
}
}

/**
* {@inheritdoc}
*/
protected function describeApplication(Application $application, array $options = []) {
$describedNamespace = $options['namespace'] ?? NULL;
$description = new ApplicationDescription($application, $describedNamespace);
$title = $this->getApplicationTitle($application);

$this->write($title . "\n" . str_repeat($this->applicationTitleUnderlineChar, Helper::width($title)));

foreach ($description->getNamespaces() as $namespace) {
if (ApplicationDescription::GLOBAL_NAMESPACE !== $namespace['id']) {
$this->write("\n\n");
$this->write('**' . $namespace['id'] . ':**');
}

$this->write("\n\n");
$this->write(implode("\n", array_map(function ($commandName) {
return sprintf('- `%s`_', $commandName);
}, $namespace['commands'])));
}
if ($help = $command->getProcessedHelp()) {
$this->write("\n");
$this->write($help);
}

foreach ($description->getCommands() as $command) {
$this->write("\n\n");
if (NULL !== $describeCommand = $this->describeCommand($command, $options)) {
$this->write($describeCommand);
}
$definition = $command->getDefinition();
if ($definition->getOptions() || $definition->getArguments()) {
$this->write("\n\n");
$this->describeInputDefinition($definition);
}
}
}

private function getApplicationTitle(Application $application): string {
if ('UNKNOWN' !== $application->getName()) {
if ('UNKNOWN' !== $application->getVersion()) {
return sprintf('%s %s', $application->getName(), $application->getVersion());
}
/**
* {@inheritdoc}
*/
protected function describeApplication(Application $application, array $options = [])
{
$describedNamespace = $options['namespace'] ?? null;
$description = new ApplicationDescription($application, $describedNamespace);
$title = $this->getApplicationTitle($application);

$this->write($title."\n".str_repeat($this->applicationTitleUnderlineChar, Helper::width($title)));

foreach ($description->getNamespaces() as $namespace) {
if (ApplicationDescription::GLOBAL_NAMESPACE !== $namespace['id']) {
$this->write("\n\n");
$this->write('**'.$namespace['id'].':**');
}

$this->write("\n\n");
$this->write(implode("\n", array_map(function ($commandName) {
return sprintf('- `%s`_', $commandName);
}, $namespace['commands'])));
}

return $application->getName();
foreach ($description->getCommands() as $command) {
$this->write("\n\n");
if (null !== $describeCommand = $this->describeCommand($command, $options)) {
$this->write($describeCommand);
}
}
}

return 'Console Tool';
}
private function getApplicationTitle(Application $application): string
{
if ('UNKNOWN' !== $application->getName()) {
if ('UNKNOWN' !== $application->getVersion()) {
return sprintf('%s %s', $application->getName(), $application->getVersion());
}

return $application->getName();
}

return 'Console Tool';
}
}
0