在单独的目录中构建翻译后的 Sphinx 文档

Question

我正在编写一份将以不同语言发布的文档。这也是我使用 Sphinx 的原因之一。

我知道如何生成翻译版本，但使用documentation 中描述的设置，生成的文件将替换之前生成的文件。因此，在生成多个翻译时，我必须先将文件移动到另一个目录，然后再执行其他任何操作。在单独的目录中生成翻译会更实用（也更容易部署）。

有没有办法告诉 Sphinx 或 makefile 当我运行时

make -e SPHINXOPTS="-D language='(lang)'" (format)

文件必须在 /build/(format)/(lang) 中生成？

目前，仅使用 HTML 构建（我怀疑是否会使用其他内容），因此如果无法在全球范围内执行特定的解决方案，则会被接受。

Sphinx 版本是 1.4.6。

Answer 1

我通过用自定义 Python 脚本 (build.py) 替换 Makefile 找到了一个可行的解决方案。

使用sys.argv，我模仿make target 的行为。我为该语言添加了几个选项。使用 subprocess 模块，确切地说是它的call() 函数，我能够运行带有一组选项的命令。该脚本基于一个函数，该函数生成subprocess.call()要执行的命令：

def build_command(target, build_dir, lang=None):
    lang_opt = []
    if lang:
        lang_opt = ["-D", "language='" + lang + "'"]
        build_dir += "/" + lang
    else:
        build_dir += "/default"

    return ["sphinx-build", "-b", target, "-aE"] + lang_opt + ["source", "build/" + build_dir]

lang 参数使我能够独立于目标来分隔每种语言。稍后在代码中，我只是运行

subprocess.call(build_command(target, target, lang))

使用指定目标（通常为target = "html"）以所需语言构建文档。它还可以模拟make gettext:

subprocess.call(build_command("gettext", "locale"))

等等……

可能存在更好的解决方案，但至少这个解决方案可以完成这项工作。