Sphinx能否指定独立于BUILDDIR/html的HTML输出路径？

嘿，这个问题我之前折腾Sphinx的时候也碰到过！确实，Sphinx默认会把HTML输出放在$(BUILDDIR)/html下面，而且官方配置里没有直接让你跳过这个子目录的选项，但有几个实用的办法能帮你省去每次复制的麻烦：

方法1：直接修改Makefile的html目标 #

最直接的方式就是改Makefile里的html构建逻辑，把输出目录换成你想要的服务器路径。

打开你的Makefile，找到类似这样的代码块：

html:
	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
	@echo
	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

然后把它改成这样：

# 定义你最终想要的HTML输出路径，比如服务器的部署目录
HTML_OUTPUT_DIR = /var/www/your-docs-site

html:
	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(HTML_OUTPUT_DIR)
	@echo
	@echo "Build finished. The HTML pages are in $(HTML_OUTPUT_DIR)."

这样执行make html的时候，Sphinx就会直接把生成的网页文件放到你指定的HTML_OUTPUT_DIR里，完全不用再手动复制了。

方法2：分离中间文件和HTML输出 #

如果你还想保留Sphinx的中间构建文件（比如doctree），但又不想让HTML输出嵌套在BUILDDIR下，可以用-d参数指定中间文件的存放目录，同时直接输出HTML到目标路径：

修改Makefile的html目标如下：

# 中间文件存放目录（比如保留在build下，不影响部署）
DOCTREE_DIR = build/doctree
# 最终HTML输出路径
HTML_OUTPUT_DIR = /var/www/your-docs-site

html:
	$(SPHINXBUILD) -b html -d $(DOCTREE_DIR) $(ALLSPHINXOPTS) $(HTML_OUTPUT_DIR)
	@echo
	@echo "Build finished. HTML pages in $(HTML_OUTPUT_DIR), build artifacts in $(DOCTREE_DIR)."

这个方法的好处是，中间构建文件和最终的HTML输出完全分开，既不影响部署，也方便后续增量构建。

方法3：跳过Makefile，直接用sphinx-build命令 #

如果不想改Makefile，也可以直接调用sphinx-build命令，手动指定源目录和输出目录：

sphinx-build -b html ./source /var/www/your-docs-site

这里./source是你的Sphinx文档源文件目录，后面的路径就是你想要的HTML输出位置。这个方式灵活度最高，适合临时或者一次性的构建需求。

补充说明 #

Sphinx默认把每种输出格式放在BUILDDIR的子目录下，是为了区分不同的构建产物（比如HTML、PDF、LaTeX等），但对于直接部署到服务器的场景确实有点繁琐。上面的几种方法都能完美绕开这个默认结构，直接输出到你想要的位置。

内容的提问来源于stack exchange，提问作者Matt Hancock