Windows PowerShell执行Makefile的make github构建Sphinx时找不到conf.py

问题根因 #

你遇到的报错由两个Windows平台兼容性问题共同导致：

1. 原Makefile中github目标使用嵌套的@make html调用，Windows下的make工具在PowerShell环境运行时，嵌套调用不会继承父Makefile定义的SOURCEDIR变量，sphinx-build默认从当前项目根目录查找conf.py，匹配不到就抛出你看到的报错。
2. cp -a是类Unix系统的命令参数，PowerShell原生不支持该参数，就算解决了构建问题，复制环节也会报错。

适配后修改方案 #

只需要替换原Makefile中的github目标段即可，修改后同时兼容Windows PowerShell、Git Bash、Linux、Mac环境：

github:
    @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
ifeq ($(OS),Windows_NT)
    @if exist "./docs" rd /s /q "./docs"
    @xcopy /e /i /y "$(BUILDDIR)\html" "./docs" > nul
else
    @cp -a build/html/. ./docs
endif

修改说明 #

• 替换嵌套make html为直接调用sphinx-build，复用顶部定义的所有变量，从根本上解决变量丢失导致的conf.py找不到问题
• 新增系统判断逻辑，Windows环境下使用原生的目录删除和复制命令，避免Linux命令参数不兼容问题，类Unix环境保留原有逻辑不受影响
• xcopy后的> nul是屏蔽复制时的文件输出日志，不需要可以删除

修改完成后在PowerShell中直接执行make github即可正常运行。

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