如何在Sphinx代码块中正常使用章节交叉引用链接

sphinx.ext.autosectionlabel扩展本身配置没有问题，链接无法渲染的核心原因是：code-block指令的设计逻辑是将块内所有内容作为纯字面量原样输出，不会解析任何RST内联语法，你写在块内的:ref:Section 1``会被直接当做普通文本展示，自然不会生成跳转链接，这是符合预期的行为，不是扩展故障。

根据你的实际需求二选一即可：

• 如果只是需要在代码块中展示配置示例，不需要:ref:标记真的跳转：现有写法不需要修改，只是:ref:Section 1``会作为配置值的一部分以纯文本形式显示。
• 如果需要对应位置生成可点击的跳转链接：把code-block指令替换为parsed-literal指令，这个指令会保留代码内容的等宽显示样式，同时正常解析块内的RST内联标记（包括交叉引用）。

修改后的doc.rst示例：

.. parsed-literal::

    FTP_ENABLED: "sgsf"
    FTP_USERNAME: asdasd
    FTP_PASSWORD: asdasd
    FTP_HOSTNAME: asdasd
    FTP_PORT: 21
    FTP_SLACK_WEBHOOK_URL: Use the URL by :ref:`Section 1`

Section 1
---------

Section text here

可以在conf.py中添加如下配置，避免文档内存在同名章节时autosectionlabel生成重复标签导致引用错乱：

autosectionlabel_prefix_document = True

添加配置后，引用章节时需要带上文档名前缀，比如上述示例的引用要写成:ref:doc:Section 1``。

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