如何在Sphinx中引入Asciidoc格式文件

方法1：使用sphinxcontrib-asciidoc扩展（推荐） #

这是官方维护的适配扩展，可直接解析Asciidoc源文件，无需手动转格式，操作步骤如下：

• 先安装依赖：执行pip install sphinxcontrib-asciidoc，同时确保本地环境已安装asciidoctor工具
• 打开Sphinx项目的conf.py配置文件，在extensions列表中添加'sphinxcontrib.asciidoc'
• 如果要在现有rst文档中嵌入单独的Asciidoc文件内容，直接在rst文件中使用.. include:: 目标文件.adoc指令即可，扩展会自动识别后缀完成解析渲染
• 如果要把.adoc文件作为独立文档页加入项目，直接在index.rst的toctree配置中正常添加.adoc文件路径即可，不需要额外转换操作
• 如需自定义Asciidoc渲染规则，可在conf.py中添加asciidoc_args = ['-a', '自定义属性名=属性值']传入asciidoctor的启动参数

方法2：使用raw节点适配（仅适合HTML输出场景） #

如果你的Asciidoc内容不需要和Sphinx的交叉引用、索引等功能联动，可以用预渲染方案快速实现：

• 先本地把Asciidoc文件批量渲染为HTML片段
• 在需要引入的rst文件中用raw指令导入渲染后的内容：

.. raw:: html
    :file: 预渲染后的HTML文件路径.html

注意该方案仅支持HTML输出格式，如果你需要生成epub、pdf等其他格式文档，不要使用该方案。

常见说明 #

如果引入的Asciidoc文件包含内部链接，需要在conf.py中将asciidoc_use_asciidoctor参数设为True，才能正确解析转换为Sphinx的内部引用格式；第三方Asciidoc文件更新后，直接替换本地.adoc源文件即可，构建时Sphinx会自动完成解析。

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