问题描述
问题是“为什么 Sphinx 不能在 Windows 中运行?”或“为什么正确安装后缺少 sphinx-build.exe?”。
我们使用 Sphinx 生成 Python 文档。它在 Linux 中运行良好,但昨天它在 Windows 中停止工作。我已经看到有关“sphinx-build.exe”丢失文件的错误报告。
我今天在 Windows 系统上找到了问题的根源。问题的症状是一个可执行文件“sphinx-build.exe”在 make 失败后从文件系统中消失。
我已经多次重复这个循环。如果我在虚拟环境中也会发生同样的情况
这是我删除并重新安装 Sphinx 后的 Scripts 目录:
Directory: C:\Users\PJPJPJ\apps\python38\Scripts
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 3/10/2021 12:40 PM 106348 sphinx-apidoc.exe
-a---- 3/10/2021 12:40 PM 106362 sphinx-autogen.exe
-a---- 3/10/2021 12:40 PM 106347 sphinx-build.exe
-a---- 3/10/2021 12:40 PM 106352 sphinx-quickstart.exe
尝试运行 sphinx-build 失败:
PS C:\Users\PJPJPJ\GIT\HRB\ml_ita\ml_ita\packages\ita\docs> make html
sh: /c/Users/PJPJPJ/apps/python38/Scripts/sphinx-build: Permission denied
make: *** [Makefile:20: html] Error 126
PS C:\Users\PJPJPJ\GIT\HRB\ml_ita\ml_ita\packages\ita\docs>
PS C:\Users\PJPJPJ\apps\python38> ls .\Scripts\sphinx*
Directory: C:\Users\PJPJPJ\apps\python38\Scripts
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 3/10/2021 12:40 PM 106348 sphinx-apidoc.exe
-a---- 3/10/2021 12:40 PM 106362 sphinx-autogen.exe
-a---- 3/10/2021 12:40 PM 106352 sphinx-quickstart.exe
我一遍又一遍地这样做,以为我快疯了。第 8 次,我注意到右下角出现了一个警告。这就解释了。 “Crowdstrike 检测到恶意软件”。东西突然弹出又消失得如此之快,我无法复制整个消息来向你展示整个事情。
啊。企业防病毒控制。
解决方法
安装 sphinx Python 包后,您有两个选项可以执行它,
- 执行
sphinx-build.exe
- 或者执行
python -m sphinx
因此,在您确切了解删除前者的内容之前,您可以尝试使用后者作为替代方法。
,为了清楚地了解我们正在谈论的内容,让我们查看相关文件/目录的列表(仅精选与手头案例相关的文件)。
C:\>tree PATH_TO_YOUR_VENV_OR_INSTALLATION
C:\PATH_TO_YOUR_VENV_OR_INSTALLATION
├───Include
├───Lib
│ └───site-packages
│ └───sphinx
│ ├──__main__.py
│ ├───cmd
│ │ ├──build.py
│ │ └──quickstart.py
│ └───ext
│ └──apidoc.py
└───Scripts
├──activate.bat
├──sphinx-apidoc.exe
├──sphinx-build.exe
└──sphinx-quickstart.exe
现在,可执行的 .exe
文件(您的防病毒软件正在删除)基本上映射到相应的 .py
模块(以上都有)。这些等效于 setuptools entry_points
,您可以在 Sphinx's setup.py
on GitHub 中看到它的实现。
调用python -m sphinx
的方案对应如下:
1.1.1。界面选项
包名称(包括命名空间包)也是允许的。当提供包名而不是普通模块时,解释器将执行
实际上,通过调用 python -m sphinx
,您正在执行 Sphinx 包,就好像它是一个模块一样,如果您在命令行上不带任何参数进行调用,则可以验证这一点,结果将是:
用法:__main__.py [OPTIONS] SOURCEDIR OUTPUTDIR [文件名...] __main__.py:错误:需要以下参数:sourcedir、outputdir、filenames
那么让我们看看上面精选的 __main__.py
文件的内容:
import sys
from sphinx.cmd.build import main
sys.exit(main(sys.argv[1:]))
这就是我写一个更广泛的答案(也为未来的读者)的原因,因为如果您的防病毒软件决定也删除 sphinx-apidoc.exe
和 sphinx-quickstart.exe
,只需使用 python -m sphinx
不会解决这些进一步的问题。
最后,当您运行 make html
时,您正在执行(很可能)使用 sphinx-quickstart
生成的 makefile。如果您的项目具有通常的文件/目录布局 (with source
separate from build
),它将如下所示:
C:\Your_Project
├───docs
│ ├──build
│ ├──source
│ ├──make.bat
│ └──makefile
│
├───src
(...)
让我们包含上面 makefile
的 4 行相关内容,以便在我们结束解释之前清楚地了解正在发生的事情:
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
这 2 个目录 SOURCEDIR
和 BUILDDIR
对应于上面介绍的 build
和 source
目录。当您调用运行 makefile
的 make html
时会发生什么正在调用具有以下签名的 sphinx-build
(来自文档):
概要
sphinx-build [选项]
可能的解决方案:
解决方案 1。您可以将对应于 SPHINXBUILD ?= sphinx-build
的行更改为 SPHINXBUILD ?= python -m sphinx
它将起作用并且您将执行 sphinx 包作为模块(如 __main__.py
文件)。
但是,如果您的防病毒软件决定删除剩余的可执行 .exe
文件(并且您还想执行这些文件),这并不能解决(也不能解决)潜在问题。 此外,在很多情况下您都希望完全避免使用 makefile,因此给出完整的解释可以解决所有这些情况。
解决方案 2。您可以直接使用 Sphinx 进行构建,无需可执行文件或 makefile。
当您调用 make html
时,您通常会在包含 makefile 的路径上执行此操作(在上面的示例中,您将从 /docs
目录中调用它)。因此,让我们考虑在不使用 makefile 时从何处调用的 2 条可能路径:
-
从
/docs
目录调用。您可以传递与执行位置相关的source
和build
目录,如下所示:python C:\PATH_TO_YOUR_VENV_OR_INSTALLATION\Lib\site-packages\sphinx\cmd\build.py -b html source build/html
-
从任何地方呼叫。您可以像这样使用
source
和build
的完整路径:python C:\PATH_TO_YOUR_VENV_OR_INSTALLATION\Lib\site-packages\sphinx\cmd\build.py -b html C:/Your_Project/docs/source C:/Your_Project/docs/build/html
这归结为使用 sphinx-build
作为脚本(更准确地说是 build.py
)显式传入完整路径来调用 Python。 (同样的方法也适用于其他可执行文件)。
这里有两个重要的注意事项:
-
如果您正在构建 HTML,则
-b
选项是必需的,因此您将在选项列表中传入-b html
。 -
在 Windows 上,路径分隔符是反斜杠
\
,但您传递给 Sphinx 的参数需要使用正斜杠/
作为分隔符。