解决Sphinx代码块内联文本解析与语法高亮冲突的指南

def visit_literal_block(self, node: Element) -> None:
    if node.rawsource != node.astext():  # 关键判断点
        # 如果 rawsource 与 astext() 不一致，则很可能是一个解析过的文本块
        # 此时，Sphinx默认不进行语法高亮
        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 sphinx.util.docutils import SphinxDirective
from docutils.parsers.rst import directives

class ParsedCodeBlock(SphinxDirective):
    """
    一个支持内联文本解析和语法高亮的Sphinx代码块指令。
    """
    has_content = True
    required_arguments = 0
    optional_arguments = 1 # language
    final_argument_whitespace = True
    option_spec = CodeBlock.option_spec # 继承CodeBlock的选项

    def run(self):
        self.assert_has_content()
        code = '\n'.join(self.content)

        # 1. 使用self.state.inline_text进行内联文本解析
        # 这将生成一系列文本节点（如Text, reference等）
        text_nodes, messages = self.state.inline_text(code, self.lineno)

        # 2. 将解析后的文本节点转换为纯文本字符串，作为literal_block的astext()内容
        # 并且，将这个纯文本字符串同时作为rawsource。
        # 这样可以确保 node.rawsource == node.astext()，从而启用语法高亮。
        parsed_code_as_text = ''.join(n.astext() for n in text_nodes)

        # 3. 创建literal_block节点
        # 第一个参数是rawsource，第二个参数是astext()的默认内容（这里我们清空，因为内容在子节点中）
        # 后续的*text_nodes是将解析后的节点作为子节点添加
        literal = nodes.literal_block(parsed_code_as_text, '', *text_nodes)

        # 设置语言和行号等选项，这些选项会传递给HTMLTranslator
        literal['language'] = self.arguments[0] if self.arguments else 'default'
        literal['linenos'] = 'linenos' in self.options
        literal['classes'] += self.options.get('class', [])
        literal['force'] = 'force' in self.options
        literal['highlight_args'] = self.options.get('highlight_args', {})

        # 返回节点和可能的消息
        return [literal] + messages

# conf.py
from docutils.parsers.rst import directives
from sphinx.util.docutils import SphinxDirective
from sphinx.directives.code import CodeBlock
from docutils import nodes

# 假设ParsedCodeBlock类已如上定义在当前文件或导入自其他模块

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

.. parsed-code-block:: python

   def hello_world():
       print("Hello, `World <https://example.com/world>`_!") # 这里的链接会被解析
       # 这是一个普通的Python注释