如何在reStructuredText中实现冒号后文本对齐并保留空格（Sphinx转HTML）

方案一：使用定义列表（推荐） #

这是最适配API术语-描述场景的原生方案，rst的定义列表会自动根据最长术语的宽度调整描述部分的缩进，渲染HTML后自然对齐，完全不需要手动调整空格或额外样式。

写法示例：

`API_MACRO_1:`
   这是第一个API的详细描述，说明其功能和用法，换行后描述内容会自动保持缩进对齐。

`API_MACRO_2_LONG_NAME:`
   这是第二个长名称API的描述，定义列表会自动匹配最长术语的宽度，让所有描述文本左对齐。

• 优点：原生语法，无需额外配置，排版整洁，适配各种渲染场景
• 注意：术语部分（冒号前的宏）用反引号包裹，保持代码样式，满足你不可修改API宏的需求

方案二：自定义无样式表格 #

如果必须用表格实现，可通过给表格添加专属类，再用CSS隐藏边框和交替行阴影，完全不影响项目中其他表格的既定样式。

步骤1：在rst中给表格添加自定义类 #

.. table:: API说明
   :class: api-align-table

   +-------------------------+------------------------------------------+
   | `API_MACRO_1:`          | 这是第一个API的详细描述，说明其功能和用法 |
   | `API_MACRO_2_LONG_NAME:`| 这是第二个长名称API的描述，需要对齐显示   |
   +-------------------------+------------------------------------------+

步骤2：添加自定义CSS #

在Sphinx项目的_static目录下创建custom.css，写入以下样式：

/* 仅针对api-align-table类的表格 */
.api-align-table {
    border: none;
    width: 100%; /* 可选，让表格占满容器宽度 */
}

.api-align-table th, .api-align-table td {
    border: none;
    padding: 4px 8px; /* 调整内边距优化排版 */
}

.api-align-table tr:nth-child(even) {
    background-color: transparent; /* 移除交替行阴影 */
}

步骤3：配置Sphinx加载自定义CSS #

在项目的conf.py中添加以下配置：

html_static_path = ['_static']
html_css_files = ['custom.css']

方案三：预格式化文本（备选） #

如果需要严格保留手动插入的空格和制表符，可使用预格式化文本块，但会自带代码块样式，需额外调整CSS优化外观。

写法示例：

.. code-block:: text

   API_MACRO_1:          这是第一个API的详细描述，说明其功能和用法
   API_MACRO_2_LONG_NAME:这是第二个长名称API的描述，需要对齐显示

优化样式的CSS（添加到custom.css）：

.code-block.text {
    background-color: transparent;
    border: none;
    font-family: inherit; /* 使用文档默认字体，替代等宽字体 */
    white-space: pre-wrap; /* 可选，自动换行 */
}

内容的提问来源于stack exchange，提问作者oz613