在单独的目录中构建已翻译的 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"))

等等...

可能存在更好的解决方案，但至少这个可以解决问题。

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

Build translated Sphinx docs in separate directories

internationalization

python-sphinx