Sphinx自定义代码块：实现内联文本解析与语法高亮

def visit_literal_block(self, node: Element) -> None:
    if node.rawsource != node.astext():  # 核心判断逻辑
        # most probably a parsed-literal block -- don't highlight
        return super().visit_literal_block(node)

    lang = node.get('language', 'default')
    linenos = node.get('linenos', False)
    # ... 进行语法高亮 ...

text_nodes, messages = self.state.inline_text(code, self.lineno)
literal: Element = nodes.literal_block(code, "", *text_nodes)

from docutils import nodes
from sphinx.directives.code import CodeBlock
from typing import List, Tuple

class ParsedHighlightedCodeBlock(CodeBlock):
    """
    一个支持内联文本解析和语法高亮的自定义代码块指令。
    """
    def run(self) -> List[nodes.Node]:
        # 获取代码内容
        code = '\n'.join(self.content)

        # 使用self.state.inline_text进行内联文本解析
        # 这会将原始代码字符串解析为一系列节点（如文本、链接等）
        text_nodes, messages = self.state.inline_text(code, self.lineno)

        # 创建一个literal_block节点，并用解析后的文本节点填充
        # 第一个参数通常是rawsource，这里我们先用原始code，
        # 后面会修正以确保语法高亮
        literal = nodes.literal_block(code, "", *text_nodes)

        # 从指令选项中获取语言和行号设置
        literal['language'] = self.arguments[0] if self.arguments else self.options.get('language', 'default')
        literal['linenos'] = 'linenos' in self.options
        literal['classes'] += self.options.get('class', [])

        # 核心修复：确保rawsource与节点实际的文本内容一致
        # 这样HTMLTranslator就不会跳过语法高亮
        literal.rawsource = literal.astext()

        # 返回包含literal_block节点和任何解析消息的列表
        return [literal] + messages

# 在Sphinx的conf.py中注册自定义指令
# def setup(app):
#     app.add_directive("parsed-highlighted-code-block", ParsedHighlightedCodeBlock)
#     return {
#         'version': '0.1',
#         'parallel_read_safe': True,
#         'parallel_write_safe': True,
#     }

# conf.py
from docutils import nodes
from sphinx.directives.code import CodeBlock
from typing import List, Tuple

# 将上述 ParsedHighlightedCodeBlock 类定义放在 conf.py 中，
# 或者导入一个单独的 Python 模块。

def setup(app):
    app.add_directive("parsed-highlighted-code-block", ParsedHighlightedCodeBlock)
    return {
        'version': '0.1',
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }

.. parsed-highlighted-code-block:: python

    def hello_world():
        # 这是一个 `链接到Sphinx文档 <https://www.sphinx-doc.org/en/master/>`_
        print("Hello, Sphinx!")