在 sphinx-build 文档生成期间检测 conf.py 中的输出格式

Question

我正在将 Sphinx 的一些问题的解决方法直接添加到 conf.py 文件中。我想写这样的代码：

if documentation_will_be_generated_as_HTML():
    my_workaround_for_html_docs()
else:
    my_workaround_for_the_rest_of_the_formats()

如何为 Sphinx 编写谓词 documentation_will_be_generated_as_HTML()？

P.S。我知道做这样的变通办法不好，最好把它们做成延期，但最后期限很严格。

Answer 1

您可以查看 conf.py 中 sys.argv 的内容来确定 buildername is being passed when you execute sphinx-build。（这是最简单直接的方法）。

sys.argv 包含的内容取决于您调用 sphinx-build 的方式。如果您使用 make html 基本上您是在调用 make 文件并将构建器名称 html 作为第二个参数传递（但是 makfile 将在调用 sphinx-build 之前对您的命令行调用进行更多更改).

然后在 conf.py 内部检查 sys.argv[2] 应该包含 html。（makefile 通常由 sphinx-quickstart 生成，并且可能因操作系统而异。）

从 Windows 上的 Sphinx make.bat 批处理文件中突出显示相关行的摘录：

if "%SPHINXBUILD%" == "" (
    set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

这是一个更复杂的运行ning sphinx-build 示例，直接从带有显式参数的命令行（不使用 makefile），它看起来像下面，在这种情况下 sys.argv[3] 包含构建器名称。

>>> sys.argv
['C:/my_venv/Lib/site-packages/sphinx/cmd/build.py', '-E', '-b', 'html', '-d', 'build/doctrees', 'source', 'build/html']

>>> sys.argv[3]
html

总而言之，取决于您运行 Sphinx 如何检查 sys.argv 包含在 conf.py 中的内容并相应地编写您的条件。在我们的示例中，取决于您调用 sphinx-build（或 make html）的精确程度：

def documentation_will_be_generated_as_HTML():
    if sys.argv[3] == 'html'
        return True


if documentation_will_be_generated_as_HTML():
    my_workaround_for_html_docs()
else:
    my_workaround_for_the_rest_of_the_formats()

Answer 2

您可以使用 Sphinx 的应用程序 API 和事件处理功能来确定当前运行的构建器。参见 https://www.sphinx-doc.org/en/master/extdev/appapi.html。

source-read 事件的处理程序可能如下所示：

def workaround(app, docname, source):
    if app.builder.name == "html":
        my_workaround_for_html_docs()
    else:
        my_workaround_for_the_rest_of_the_formats()
 
def setup(app):
    app.connect("source-read", workaround)

其他一些活动可能更适合您的具体情况。

在 sphinx-build 文档生成期间检测 conf.py 中的输出格式

Detect output format in conf.py during sphinx-build documentation generation

python

python-sphinx