Sphinx为何将rST行内literal解析为code？

背景认知与疑问 #

• Docutils的规则里，文本外的双反引号等价于:literal:角色，同时还有专门的:code:角色用于标记行内代码，而且Docutils并没有明确说明所有literal都属于code范畴。
• 但Sphinx文档明确表示反引号用来表示行内代码，且生成HTML时，所有非kbd类型的literal都会被解析成<code>元素。
• 你认为这和Docutils的设计意图不符，想弄清Sphinx这么处理的原因，或是确认自身认知是否有误。

认知确认与原因解析 #

首先可以明确：你的认知完全正确，Docutils的设计确实区分了:literal:和:code:的语义：

• :literal:的核心是保留文本原样输出，用途更宽泛——可以标记任何需要原样展示的内容，比如配置参数值、命令行输出片段、甚至是需强调格式的普通文本，不一定特指代码。
• :code:则是语义明确的代码标记角色，专门用来指代编程语言代码、指令这类内容。

至于Sphinx的处理逻辑，主要源于以下几点：

1. 简化用户操作：Sphinx面向大量技术文档作者，统一把反引号（对应literal）映射到<code>元素，能减少用户需要记忆的角色类型，降低使用门槛——毕竟绝大多数技术文档场景里，用literal标记的内容都是代码相关的。
2. 适配HTML输出实用性：在HTML生态中，<code>是最通用的代码标记标签，用户浏览技术文档时也习惯通过这个标签的样式识别代码内容。Sphinx优先考虑了输出结果的实用性和用户浏览体验，而非严格遵循Docutils的语义区分。
3. 预留自定义空间：如果确实需要严格区分literal和code的语义，Sphinx支持通过扩展或自定义角色调整。比如可以重新定义:literal:的输出样式，或是创建自定义角色来标记非代码类的原样文本。

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