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

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

我正在将一些 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()？

附言我知道这样制定变通办法不好，最好把它们做成延期，但截止日期很严格。

解决方法

您可以检查 Map() 中 sys.argv 的内容，以确定执行 buildername 时传递的是什么 sphinx-build。（这是最简单直接的方法）。

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

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

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

make.bat

这是一个更复杂的示例，它使用显式参数（不使用 makefile）直接从命令行运行 if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) set SOURCEDIR=source set BUILDDIR=build %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%，它如下所示，在这种情况下，sphinx-build 包含构建器名称。

sys.argv[3]

总而言之，根据您运行 Sphinx 的方式，检查 >>> 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 包含在 sys.argv 中的内容并相应地编写您的条件。在我们的示例中，具体取决于您调用 conf.py（或 sphinx-build）的方式：

make html

您可以使用 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)

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