Symfony Console RST 描述符（ReStructuredTextDescriptor）实战：读懂 command_2.rst 测试夹具与命令文档化输出

Symfony 的 Console 组件不仅负责命令的注册与执行，还内置了一套"命令描述（Descriptor）"子系统，能够把命令、参数、选项甚至整个应用结构，序列化为纯文本、XML、JSON、Markdown 与 reStructuredText（RST）等多种文档格式。本文以仓库中的测试夹具 command_2.rst 为入口，讲解 RST 描述符的输出结构、其对应的命令定义源码、测试驱动方式，以及如何在实际项目里用 --format=rst 生成可直接进入 Sphinx 文档的命令手册。

1. 一个 RST 夹具的完整解剖：command_2.rst

command_2.rst 是 Console 组件测试套件中的"预期输出"（expected output）文件，与同目录下的 command_2.md、command_2.json、command_2.txt、command_2.xml 一一对应，分别验证五种描述格式对同一个命令对象的渲染结果。其完整内容如下：

descriptor:command2
...................

command 2 description

Usage
^^^^^

- ``descriptor:command2 [-o|--option_name] [--] <argument_name>``
- ``descriptor:command2 -o|--option_name <argument_name>``
- ``descriptor:command2 <argument_name>``

command 2 help

Arguments
^^^^^^^^^

argument_name

Options
^^^^^^^

\-\-option_name|-o
""""""""""""""""""

- **Accept value**: no
- **Is value required**: no
- **Is multiple**: no
- **Is negatable**: no
- **Is deprecated**: no
- **Is hidden**: no
- **Default**: ``false``

虽然只有 32 行，但它完整覆盖了 RST 描述符（ReStructuredTextDescriptor.php）渲染一个命令时输出的全部组成部分：

夹具区块	含义	对应源码方法
标题 + ..... 下划线	命令名作为小节标题（h4 级别）	describeCommand()
描述行	setDescription() 设置的命令简介	describeCommand()
Usage 段	命令 synopsis + 自定义 usage 列表	describeCommand() + getSynopsis()
帮助文本	setHelp() 设置的完整帮助	getProcessedHelp()
Arguments 段	参数名与必填/数组/默认值	describeInputArgument()
Options 段	选项全名、短名与 7 项属性	describeInputOption()

注意 RST 中反斜杠的转义：选项标题写作 \-\-option_name|-o，这是 RST 语法中对 -- 的转义写法，避免被误解析为段落标记。

2. 夹具背后的命令定义：DescriptorCommand2

command_2.rst 描述的对象不是虚拟内容，而是 DescriptorCommand2.php 中定义的、真实可执行的命令实例：

class DescriptorCommand2 extends Command
{
    protected function configure(): void
    {
        $this
            ->setName('descriptor:command2')
            ->setDescription('command 2 description')
            ->setHelp('command 2 help')
            ->addUsage('-o|--option_name <argument_name>')
            ->addUsage('<argument_name>')
            ->addArgument('argument_name', InputArgument::REQUIRED)
            ->addOption('option_name', 'o', InputOption::VALUE_NONE)
        ;
    }
}

逐行对应夹具中的输出，可以看到描述符如何忠实反映命令定义：

• setName('descriptor:command2') → 决定 RST 标题行与 Usage 第一条 synopsis 中的命令名。
• setDescription(...) → 直接输出为标题下方的简介行。
• setHelp(...) → 输出在 Usage 列表之后，作为独立段落。
• 两条 addUsage(...) → 与 getSynopsis() 自动生成的默认用法合并，共同构成 Usage 的三条列表项：
  • 第一条 descriptor:command2 [-o|--option_name] [--] <argument_name> 是组件自动拼装的 synopsis；
  • 后两条是开发者显式追加的补充用法。
• addArgument('argument_name', InputArgument::REQUIRED) → 生成 Arguments 段落中的 argument_name 小节。
• addOption('option_name', 'o', InputOption::VALUE_NONE) → 生成 Options 段落，VALUE_NONE 直接决定 **Accept value**: no、**Is value required**: no、`Default: ``false``` 三行输出。

2.1 为什么夹具只有参数名、没有参数属性行？

细心的读者会发现：command_2.rst 的 Arguments 段只有 argument_name 一个名字，没有列出 Is required 等属性，而同目录的 command_2.md 中却包含：

#### `argument_name`

* Is required: yes
* Is array: no
* Default: `NULL`

这不是 bug，而是 RST 与 Markdown 两种描述符的输出差异。对照源码 ReStructuredTextDescriptor.php 的 describeInputArgument()，RST 格式对参数只输出名称 + 描述（本例无描述），而 Markdown 描述符（MarkdownDescriptor）则额外输出 required/array/default 元信息。这也提醒我们：不同描述格式对同一命令的信息详略并不一致，选择格式时要结合目标受众。

3. 逐段源码级解读：RST 描述符如何生成这份文档

ReStructuredTextDescriptor 继承自 Descriptor 抽象基类，实现了 DescriptorInterface。它内部定义了一组字符常量用于模拟 RST 的六级标题：

private string $partChar = '=';          // <h1>
private string $chapterChar = '-';       // <h2>
private string $sectionChar = '~';       // <h3>
private string $subsectionChar = '.';    // <h4>
private string $subsubsectionChar = '^'; // <h5>
private string $paragraphsChar = '"';    // <h6>

对照 command_2.rst：

• 命令名标题使用 .....（subsectionChar，h4 级别）——因为命令是应用文档树的第四层；
• Usage、Arguments、Options 三个小节标题使用 ^^^^^（subsubsectionChar，h5 级别）；
• 选项标题 \-\-option_name|-o 使用 """""（paragraphsChar，h6 级别）。

标题下划线长度不是拍脑袋写的，而是通过 Helper::width() 按标题实际宽度动态生成，保证 RST 下划线严格对齐标题。

3.1 选项属性的七个维度

在 describeInputOption() 中，每个选项固定输出七个布尔属性，command_2.rst 中 --option_name|-o 的七行正是它们的渲染结果：

属性行	判断方法	本夹具取值	含义
Accept value	acceptValue()	no	选项是否接受值（VALUE_NONE 为否）
Is value required	isValueRequired()	no	值是否必填（VALUE_REQUIRED）
Is multiple	isArray()	no	是否可重复传入（VALUE_IS_ARRAY）
Is negatable	isNegatable()	no	是否自动生成 --no-xxx 反向选项
Is deprecated	isDeprecated()	no	是否标记为废弃
Is hidden	isHidden()	no	是否对用户隐藏
Default	getDefault()	false	默认值（var_export 序列化）

若选项声明了 VALUE_NONE 以外的模式，相应行会变为 yes。例如 VALUE_REQUIRED 选项会输出 **Accept value**: yes 与 **Is value required**: yes，默认值则按 var_export() 的真实结果输出（如 NULL、数组等）。

3.2 全局默认选项的过滤

RST 描述符在渲染命令的选项列表前，会调用 getNonDefaultOptions() 过滤掉一组"全局默认选项"：

$globalOptions = ['help', 'silent', 'quiet', 'verbose', 'version', 'ansi', 'no-interaction'];

这解释了为什么 command_2.rst 的 Options 段只有 --option_name 一个选项——help、quiet 等由 Console 应用注入的全局选项被有意剔除，只保留命令自身定义的选项，避免重复噪音。

3.3 隐藏命令与别名的处理

describeApplication() 流程中，removeAliasesAndHiddenCommands() 会剔除隐藏命令和纯别名命令，并总是移除 completion 命令；setVisibleNamespaces() 则负责在应用级渲染时跳过"只含别名或隐藏命令"的命名空间。这些逻辑保证生成的应用文档目录（Table of Contents）干净、准确。

4. 测试如何驱动这份夹具：ReStructuredTextDescriptorTest

command_2.rst 不是孤立的静态文件，它由 ReStructuredTextDescriptorTest.php 消费。该测试类继承自 AbstractDescriptorTestCase.php，共用同一套测试骨架：

protected function getDescriptor()
{
    return new ReStructuredTextDescriptor();
}

protected static function getFormat()
{
    return 'rst';
}

核心机制在抽象基类的 getDescriptionTestData() 中：按格式名拼接夹具路径，把 ObjectsProvider 提供的对象与夹具文件一一配对：

$description = file_get_contents(sprintf('%s/../Fixtures/%s.%s', __DIR__, $name, static::getFormat()));
$data[] = [$object, $description];

而命令对象来自 ObjectsProvider.php：

'command_2' => new DescriptorCommand2(),

assertDescription() 使用 BufferedOutput 捕获描述符输出，并与夹具内容做规范化后（统一换行符、替换 PHP_SELF 等占位符）的精确断言：

$output = new BufferedOutput(BufferedOutput::VERBOSITY_NORMAL, true);
$this->getDescriptor()->describe($output, $describedObject, $options + ['raw_output' => true, 'terminal_width' => PHP_INT_MAX]);
$this->assertEquals($this->normalizeOutput($expectedDescription), $this->normalizeOutput($output->fetch()));

也就是说：只要描述符渲染逻辑发生变化，command_2.rst 等夹具文件与测试就会同时失效——这些 .rst/.md/.json/.txt/.xml 五格式夹具共同构成了描述符输出的"黄金快照"，防止格式化输出被无意破坏。

5. 在实际项目中启用 RST 描述符输出

5.1 通过 list 命令切换格式

从源码 ListCommand.php 可以看到，list 命令提供了 --format 选项：

new InputOption('format', null, InputOption::VALUE_REQUIRED,
    'The output format (txt, xml, json, or md)', 'txt',
    static fn () => (new DescriptorHelper())->getFormats()),

默认格式是 txt。要获得 RST 输出，运行：

# 描述单个命令
php bin/console list --format=rst descriptor:command2

# 描述整个应用的所有命令
php bin/console list --format=rst

生成的 RST 文档可直接嵌入 Sphinx 项目，自动获得章节标题、交叉引用与目录树能力。

5.2 五种格式注册表

格式分发由 DescriptorHelper.php 完成，ReStructuredTextDescriptor 以 rst 为键注册：

$this
    ->register('txt',  new TextDescriptor())
    ->register('xml',  new XmlDescriptor())
    ->register('json', new JsonDescriptor())
    ->register('md',   new MarkdownDescriptor())
    ->register('rst',  new ReStructuredTextDescriptor())
;

describe() 方法根据 format 选项查找对应描述符，未知格式抛出 InvalidArgumentException（"Unsupported format ..."），并支持通过 register() 扩展自定义格式。

5.3 在应用代码中编程调用

如果要在自定义命令或脚本里复用描述能力，可以注入 DescriptorHelper 并指定格式：

use Symfony\Component\Console\Helper\DescriptorHelper;
use Symfony\Component\Console\Output\BufferedOutput;

$helper = new DescriptorHelper();
$output = new BufferedOutput();

// 渲染单个命令为 RST 文档
$helper->describe($output, $command, ['format' => 'rst']);

// 渲染整个应用为 RST 文档
$helper->describe($output, $application, ['format' => 'rst']);

将 BufferedOutput 的内容写入 .rst 文件，即可在每次部署时自动生成命令手册，保持文档与代码同步。

5.4 RST 描述符的装饰器处理

ReStructuredTextDescriptor::describe() 开头有一段特殊处理：临时关闭输出装饰（ANSI 颜色），渲染完成后再恢复。RST 是纯文本标记格式，颜色码会污染标记语法，因此描述符强制 setDecorated(false)，保证生成的 .rst 干净可用。

6. 小结

从 32 行的 command_2.rst 夹具出发，可以完整还原 Symfony Console 描述符子系统的设计：

1. 定义即文档：DescriptorCommand2 中的 setName/setDescription/setHelp/addUsage/addArgument/addOption 声明，经 ReStructuredTextDescriptor 渲染为结构化 RST 手册，无需任何额外编写；
2. 五格式并存：txt、xml、json、md、rst 五种描述符共享同一套测试骨架与夹具快照，行为通过 AbstractDescriptorTestCase 统一校验；
3. 信息有取舍：RST 格式对参数只输出名称与描述，而对选项输出七维属性；全局默认选项被过滤、隐藏命令与别名被剔除——这些策略共同决定了最终文档的形态；
4. 开箱即用：list --format=rst 或 DescriptorHelper->describe(..., ['format' => 'rst']) 即可把命令结构直接输出为适合 Sphinx 文档站点的 RST 源文件。

对开发者而言，理解这份夹具等同于理解 Console 命令自省（self-description）机制的全貌——它是构建 CLI 工具自动文档、自动补全与结构化输出的基石。