[BUGFIX] Use Symfony application description to render reference

.gitattributes

@@ -1,3 +1,4 @@
+/Commands/ export-ignore
 /Resources/Private/ExtensionArtifacts/src/ export-ignore
 /Resources/Private/ExtensionArtifacts/ext_localconf.php export-ignore
 /Tests/ export-ignore

Classes/Command/CacheCommandController.php

@@ -122,7 +122,7 @@ public function flushCompleteCommand($filesOnly = false)
      * - pages
      * - system
      *
-     * <b>Example:</b> <code>%command.full_name% cache:flushgroups pages,all</code>
+     * <b>Example:</b> <code>%command.full_name% pages,all</code>
      *
      * @param array $groups An array of names (specified as comma separated values) of cache groups to flush
      */
@@ -142,7 +142,7 @@ public function flushGroupsCommand(array $groups)
      *
      * Flushes caches by tags, optionally only caches in specified groups.
      *
-     * <b>Example:</b> <code>%command.full_name% cache:flushtags news_123 --groups pages,all</code>
+     * <b>Example:</b> <code>%command.full_name% news_123 --groups pages,all</code>
      *
      * @param array $tags Array of tags (specified as comma separated values) to flush.
      * @param array $groups Optional array of groups (specified as comma separated values) for which to flush tags. If no group is specified, caches of all groups are flushed.

Classes/Command/CleanupCommandController.php

@@ -37,7 +37,7 @@ public function __construct(PersistenceIntegrityService $persistenceIntegritySer
      *
      * Updates reference index to ensure data integrity
      *
-     * <b>Example:</b> <code>%command.full_name% cleanup:updatereferenceindex --dry-run --verbose</code>
+     * <b>Example:</b> <code>%command.full_name% --dry-run --verbose</code>
      *
      * @param bool $dryRun If set, index is only checked without performing any action
      * @param bool $showProgress Whether or not to output a progress bar

Classes/Command/ConfigurationCommandController.php

@@ -44,7 +44,7 @@ public function __construct(ConfigurationService $configurationService, ConsoleR
      * For this command to succeed, the configuration option(s) must be in
      * LocalConfiguration.php and not be overridden elsewhere.
      *
-     * <b>Example:</b> <code>%command.full_name% configuration:remove DB,EXT/EXTCONF/realurl</code>
+     * <b>Example:</b> <code>%command.full_name% DB,EXT/EXTCONF/realurl</code>
      *
      * @param array $paths Path to system configuration that should be removed. Multiple paths can be specified separated by comma
      * @param bool $force If set, does not ask for confirmation
@@ -78,7 +78,7 @@ public function removeCommand(array $paths, $force = false)
      * If the currently active configuration differs from the value in LocalConfiguration.php
      * the difference between these values is shown.
      *
-     * <b>Example:</b> <code>%command.full_name% configuration:show DB</code>
+     * <b>Example:</b> <code>%command.full_name% DB</code>
      *
      * @param string $path Path to system configuration option
      */
@@ -111,7 +111,7 @@ public function showCommand($path)
      * Shows active system configuration by path.
      * Shows the configuration value that is currently effective, no matter where and how it is set.
      *
-     * <b>Example:</b> <code>%command.full_name% configuration:showActive DB --json</code>
+     * <b>Example:</b> <code>%command.full_name% DB --json</code>
      *
      * @param string $path Path to system configuration
      * @param bool $json If set, the configuration is shown as JSON
@@ -131,9 +131,9 @@ public function showActiveCommand($path, $json = false)
      *
      * Shows local configuration option value by path.
      * Shows the value which is stored in LocalConfiguration.php.
-     * Note that this value could be overridden. Use <code>%command.full_name% configuration:show <path></code> to see if this is the case.
+     * Note that this value could be overridden. Use <code>typo3cms configuration:show <path></code> to see if this is the case.
      *
-     * <b>Example:</b> <code>%command.full_name% configuration:showlocal DB</code>
+     * <b>Example:</b> <code>%command.full_name% DB</code>
      *
      * @param string $path Path to local system configuration
      * @param bool $json If set, the configuration is shown as JSON
@@ -154,7 +154,7 @@ public function showLocalCommand($path, $json = false)
      *
      * Set system configuration option value by path.
      *
-     * <b>Example:</b> <code>%command.full_name% configuration:set SYS/fileCreateMask 0664</code>
+     * <b>Example:</b> <code>%command.full_name% SYS/fileCreateMask 0664</code>
      *
      * @param string $path Path to system configuration
      * @param string $value Value for system configuration

Classes/Command/DatabaseCommandController.php

@@ -74,7 +74,7 @@ public function __construct(SchemaService $schemaService, SchemaUpdateResultRend
      *
      * To avoid shell matching all types with wildcards should be quoted.
      *
-     * <b>Example:</b> <code>%command.full_name% database:updateschema "*.add,*.change"</code>
+     * <b>Example:</b> <code>%command.full_name% "*.add,*.change"</code>
      *
      * @param array $schemaUpdateTypes List of schema update types (default: "safe")
      * @param bool $dryRun If set the updates are only collected and shown, but not executed
@@ -121,9 +121,9 @@ public function updateSchemaCommand(array $schemaUpdateTypes = ['safe'], $dryRun
      * The mysql binary must be available in the path for this command to work.
      * This obviously only works when MySQL is used as DBMS.
      *
-     * <b>Example (import):</b> <code>ssh remote.server '/path/to/%command.full_name% database:export' | %command.full_name% database:import</code>
-     * <b>Example (select):</b> <code>echo 'SELECT username from be_users WHERE admin=1;' | %command.full_name% database:import</code>
-     * <b>Example (interactive):</b> <code>%command.full_name% database:import --interactive</code>
+     * <b>Example (import):</b> <code>ssh remote.server '/path/to/typo3cms database:export' | %command.full_name%</code>
+     * <b>Example (select):</b> <code>echo 'SELECT username from be_users WHERE admin=1;' | %command.full_name%</code>
+     * <b>Example (interactive):</b> <code>%command.full_name% --interactive</code>
      *
      * <warning>This command passes the plain text database password to the command line process.</warning>
      * This means, that users that have the permission to observe running processes,
@@ -154,7 +154,7 @@ public function importCommand($interactive = false)
      *
      * A comma-separated list of tables can be passed to exclude from the export:
      *
-     * <b>Example:</b> <code>%command.full_name% database:export --exclude-tables be_sessions,fe_sessions,sys_log</code>
+     * <b>Example:</b> <code>%command.full_name% --exclude-tables be_sessions,fe_sessions,sys_log</code>
      *
      * <warning>This command passes the plain text database password to the command line process.</warning>
      * This means, that users that have the permission to observe running processes,

Classes/Command/HelpCommandController.php

@@ -22,22 +22,6 @@
  */
 class HelpCommandController extends CommandController
 {
-    /**
-     * Help
-     *
-     * Display help for a command
-     *
-     * The help command displays help for a given command:
-     * %command.full_name% help <command identifier>
-     *
-     * @param string $commandIdentifier Identifier of a command for more details
-     * @return void
-     */
-    public function helpCommand($commandIdentifier)
-    {
-        // Intentionally empty for now (until command reference can render Symfony commands)
-    }
-
     /**
      * Displays an error message
      *

Classes/Command/InstallCommandController.php

@@ -127,7 +127,7 @@ public function setupCommand(
      *
      * This updates your composer.json and composer.lock without any other changes.
      *
-     * <b>Example:</b> <code>%command.full_name% install:generatepackagestates</code>
+     * <b>Example:</b> <code>%command.full_name%</code>
      *
      * @param array $frameworkExtensions TYPO3 system extensions that should be marked as active. Extension keys separated by comma.
      * @param array $excludedExtensions Extensions which should stay inactive. This does not affect provided framework extensions or framework extensions that are required or part as minimal usable system.
@@ -180,7 +180,7 @@ public function generatePackageStatesCommand(array $frameworkExtensions = [], ar
      *
      * This command creates the required folder structure needed for TYPO3 including extensions.
      * It is recommended to be executed <b>after</b> executing
-     * <code>%command.full_name% install:generatepackagestates</code>, to ensure proper generation of
+     * <code>typo3cms install:generatepackagestates</code>, to ensure proper generation of
      * required folders for all active extensions.
      *
      * @see typo3_console:install:generatepackagestates

Classes/Command/SchedulerCommandController.php

@@ -33,7 +33,7 @@ public function __construct(Scheduler $scheduler)
      *
      * Executes tasks that are registered in the scheduler module.
      *
-     * <b>Example:</b> <code>%command.full_name% scheduler:run 42 --force</code>
+     * <b>Example:</b> <code>%command.full_name% 42 --force</code>
      *
      * @param int $task Uid of the task that should be executed (instead of all scheduled tasks)
      * @param bool $force The execution can be forced with this flag. The task will then be executed even if it is not scheduled for execution yet. Only works, when a task is specified.

Classes/Mvc/Cli/CommandCollection.php

@@ -33,6 +33,14 @@
  */
 class CommandCollection implements CommandLoaderInterface
 {
+    /**
+     * Only use for rendering the reference
+     *
+     * @var bool
+     * @internal
+     */
+    public static $rendersReference = false;
+
     /**
      * @var BaseCommand[]
      */
@@ -77,7 +85,7 @@ public function __construct(RunLevel $runLevel, PackageManager $packageManager)
      */
     public function get($name): BaseCommand
     {
-        if (!isset($this->commands[$name]) || !$this->runLevel->isCommandAvailable($name)) {
+        if (!isset($this->commands[$name]) || !$this->isCommandAvailable($name)) {
             throw new CommandNotFoundException(sprintf('A command with name "%s" could not be found.', $name), 1518812618);
         }
         $command = $this->commands[$name]['closure']();
@@ -93,7 +101,7 @@ public function get($name): BaseCommand
      */
     public function has($name): bool
     {
-        return isset($this->commands[$name]) && $this->runLevel->isCommandAvailable($name);
+        return isset($this->commands[$name]) && $this->isCommandAvailable($name);
     }
 
     /**
@@ -115,6 +123,14 @@ public function addCommandControllerCommands(CommandManager $commandManager)
         $this->populateCommandControllerCommands($commandManager);
     }
 
+    private function isCommandAvailable(string $name): bool
+    {
+        if (self::$rendersReference) {
+            return true;
+        }
+        return $this->runLevel->isCommandAvailable($name);
+    }
+
     private function populateCommands()
     {
         if ($this->commands !== null) {

Classes/Mvc/Cli/Symfony/Command/CommandControllerCommand.php

@@ -42,6 +42,14 @@
  */
 class CommandControllerCommand extends Command
 {
+    /**
+     * Only use for rendering the reference
+     *
+     * @var bool
+     * @internal
+     */
+    public static $rendersReference = false;
+
     /**
      * @var CommandDefinition
      */
@@ -65,8 +73,16 @@ public function getNativeDefinition()
         return $commandInputDefinition;
     }
 
+    public function getRelatedCommandNames()
+    {
+        return $this->commandDefinition->getRelatedCommandIdentifiers();
+    }
+
     public function isEnabled(): bool
     {
+        if (self::$rendersReference) {
+            return true;
+        }
         if ($this->application->isComposerManaged()
             && $this->getName() === 'extension:dumpautoload'
         ) {
@@ -155,6 +171,9 @@ public function isHidden(): bool
                 'extension:removeinactive',
             ], true)
         ) {
+            if (self::$rendersReference) {
+                return false;
+            }
             return true;
         }
         return $this->commandDefinition->isInternal();

Commands/CreateReferenceCommand/.gitignore

@@ -0,0 +1,2 @@
+/vendor
+/composer.lock

Commands/CreateReferenceCommand/Configuration/Console/Commands.php

@@ -0,0 +1,13 @@
+<?php
+return [
+    'commands' => [
+        'commandreference:render' => [
+            'class' => \Typo3Console\CreateReferenceCommand\Command\CommandReferenceRenderCommand::class,
+        ],
+    ],
+    'runLevels' => [
+        'typo3-console/create-reference-command:commandreference:render' => \Helhum\Typo3Console\Core\Booting\RunLevel::LEVEL_COMPILE,
+    ],
+    'bootingSteps' => [
+    ],
+];

Commands/CreateReferenceCommand/Resources/Templates/CommandReferenceTemplate.txt

@@ -0,0 +1,75 @@
+{namespace d=Typo3Console\CreateReferenceCommand\ViewHelpers}
+.. include:: ../Includes.txt
+
+
+.. _typo3_console-command-reference:
+
+{title -> d:format.underline(withCharacter: '=')}
+
+.. note::
+
+  This reference uses ``{commandName}`` as the command to invoke. If you are on
+  Windows, this will probably not work, there you need to use ``{commandName}.bat``
+  instead.
+  In Composer based installations, the ``{commandName}`` binary will be located
+  in the binary directory specified in the root composer.json (by default ``vendor/bin``)
+
+
+The following reference was automatically generated from code.
+
+<d:format.underline withCharacter="-">*TYPO3 Console*</d:format.underline>
+
+Application Options
+*******************
+
+The following options can be used with every command:
+
+<f:for each="{applicationOptions}" key="name" as="description">``{name}``
+  {description.description -> f:format.raw()}
+</f:for>
+
+<f:for each="{allCommandsByPackageKey}" as="allCommands" key="packageKey">
+.. _`{title}: {packageKey}`:
+
+Available Commands
+******************
+
+<f:for each="{allCommands}" as="command">
+.. _`{title}: {packageKey} {command.identifier}`:
+
+<d:format.underline withCharacter="*">``{command.identifier}``</d:format.underline>
+
+**{command.shortDescription}**
+
+{command.description -> f:format.raw()}
+
+<f:if condition="{command.arguments}">Arguments
+^^^^^^^^^
+
+<f:for each="{command.arguments}" key="name" as="description">``{name}``
+  {description -> f:format.raw()}
+</f:for>
+</f:if>
+
+<f:if condition="{command.options}">Options
+^^^^^^^
+
+<f:for each="{command.options}" key="name" as="description">``{name}``
+  {description.description -> f:format.raw()}
+
+- Accept value: {description.acceptValue}
+- Is value required: {description.isValueRequired}
+- Is multiple: {description.isMultiple}
+- Default: {description.default -> f:format.raw()}
+
+</f:for>
+</f:if>
+
+<f:if condition="{command.relatedCommands}">Related commands
+^^^^^^^^^^^^^^^^
+
+<f:for each="{command.relatedCommands}" key="relatedCommandIdentifier" as="relatedCommandDescription">``{relatedCommandIdentifier}``
+  {relatedCommandDescription -> f:format.raw()}
+</f:for>
+</f:if>
+</f:for></f:for>

Commands/CreateReferenceCommand/composer.json

@@ -0,0 +1,26 @@
+{
+    "name": "typo3-console/create-reference-command",
+    "description": "TYPO3 Console command that creates the command reference",
+    "license": "GPL-2.0-or-later",
+    "type": "typo3-console-command",
+    "authors": [
+        {
+            "name": "Helmut Hummel",
+            "email": "info@helhum.io"
+        }
+    ],
+    "autoload": {
+        "psr-4": {
+            "Typo3Console\\CreateReferenceCommand\\": "src/"
+        }
+    },
+    "require": {
+        "php": ">=7.0 <7.3",
+        "helhum/typo3-console": "^5.0"
+    },
+    "extra": {
+        "branch-alias": {
+            "dev-master": "1.0.x-dev"
+        }
+    }
+}