如何通过Python脚本调用Sphinx渲染单个RST文件为HTML

我完全懂你想要那种极简调用的心情——命令行来回切换、手动配置项目结构实在太麻烦了。虽然Sphinx官方没有提供sphinx.render()这种一步到位的API，但我们可以自己封装一个完全符合你预期的函数，把所有繁琐的细节都藏在内部：

封装好的简洁函数 #

import os
import tempfile
from sphinx.cmd.build import build_main

def sphinx_render(rst_file: str, output_file: str):
    # 创建临时源目录，模拟Sphinx项目结构
    with tempfile.TemporaryDirectory() as temp_src_dir:
        # 1. 复制目标RST文件到临时目录，命名为index.rst（Sphinx默认入口）
        temp_rst_path = os.path.join(temp_src_dir, "index.rst")
        with open(rst_file, "r", encoding="utf-8") as src_f, open(temp_rst_path, "w", encoding="utf-8") as dest_f:
            dest_f.write(src_f.read())
        
        # 2. 创建最小化的conf.py（Sphinx必须的配置文件）
        minimal_conf = """
project = "Temp Render"
author = "Auto Generated"
extensions = []  # 这里可以添加你需要的Sphinx扩展，比如['sphinx.ext.todo']
source_suffix = ".rst"
html_theme = "alabaster"  # 可选，指定HTML主题，默认是alabaster
"""
        conf_path = os.path.join(temp_src_dir, "conf.py")
        with open(conf_path, "w", encoding="utf-8") as f:
            f.write(minimal_conf)
        
        # 3. 创建临时输出目录存放Sphinx生成的文件
        with tempfile.TemporaryDirectory() as temp_out_dir:
            # 调用Sphinx的核心构建函数
            build_args = ["-b", "html", temp_src_dir, temp_out_dir]
            build_main(build_args)
            
            # 4. 把生成的HTML复制到目标输出文件
            generated_html = os.path.join(temp_out_dir, "index.html")
            with open(generated_html, "r", encoding="utf-8") as src_f, open(output_file, "w", encoding="utf-8") as dest_f:
                dest_f.write(src_f.read())

调用方式（完全符合你的预期） #

# 直接调用，搞定！
sphinx_render(rst_file="myfile.rst", output_file="myfile.html")

关键细节说明 #

• 临时目录自动处理：函数内部用tempfile.TemporaryDirectory()自动创建/清理临时的Sphinx项目结构，你完全不用手动创建源目录、conf.py这些东西。
• 支持Sphinx专属语法：因为我们用的是Sphinx官方的构建API，所以你的RST文件里的Sphinx专属指令（比如.. note::、.. code-block:: python）都能正常渲染。
• 可扩展配置：如果你的RST用到了特定的Sphinx扩展（比如todo、autodoc），只需要修改minimal_conf里的extensions列表即可。
• 主题自定义：可以修改html_theme参数换成你喜欢的Sphinx主题，比如"sphinx_rtd_theme"（需要提前安装这个包）。

这个方案把所有复杂的Sphinx项目配置都封装起来了，调用起来就像你想要的那样简洁，完全在Python脚本内完成，不用碰命令行。

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