sphinx-build文档生成时如何在conf.py中判断输出是否为HTML格式
在Sphinx的conf.py中判断当前构建是否为HTML格式
核心实现
直接利用Sphinx内置的tags全局对象实现判断,该对象会在conf.py加载阶段自动注入作用域,天然携带当前选用构建器的标识,兼容所有主流Sphinx版本,不需要额外导入依赖、不需要手动解析命令行参数:
def documentation_will_be_generated_as_HTML() -> bool: # 覆盖所有本质输出静态HTML内容的构建器 html_related_builders = ("html", "dirhtml") return any(builder_tag in tags for builder_tag in html_related_builders)
直接接入原有分支逻辑
把上面的函数放到conf.py的任意可执行位置,直接替换原有示例里的占位判断即可:
if documentation_will_be_generated_as_HTML(): my_workaround_for_html_docs() else: my_workaround_for_the_rest_of_the_formats()
实现注意事项
- 这套逻辑完全在conf.py的加载阶段完成判断,不需要挂钩任何Sphinx生命周期事件,完全匹配快速修复的临时落地需求
- 不需要手动解析
sys.argv获取构建参数:Sphinx不同版本的命令行参数格式可能存在调整,靠手动解析参数容易出现兼容bug,而内置的tags是公开稳定的API,从早期1.x版本就存在统一的行为 - 可灵活调整判断范围:如果不需要将
dirhtml这类输出结构优化的静态HTML构建纳入判断范围,只保留'html'单值即可;如果项目引入了第三方自定义的HTML类构建器,只需要把对应的builder名称追加到元组中,不需要改动核心判断逻辑
注:该实现属于赶交付节点的临时方案,长期维护建议将这类逻辑封装为独立Sphinx扩展,通过
builder-inited事件触发对应规避规则,减少conf.py的代码冗余。
内容的提问来源于stack exchange,提问作者FedyuninV
相关产品推荐
相关产品推荐

