Windows Python: sphinx-build.exe 文件 "disappears"

Question

问题是“为什么 Sphinx 在 Windows 中不起作用？”或“为什么正确安装后 sphinx-build.exe 不见了？”。

我有一个答案，就在这里。

我们使用 Sphinx 生成 Python 文档。它在 Linux 中工作正常，但昨天它在 Windows 中停止工作。我已经看到有关“sphinx-build.exe”丢失文件的错误报告。

我今天在 Windows 系统上找到了问题的根源。问题的症状是可执行文件“sphinx-build.exe”在 make 失败后从文件系统中消失。

这个循环我已经重复了好几次了。如果我在虚拟环境中也会发生同样的情况

这是删除并重新安装 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         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 检测到恶意软件”。东西弹出又消失得如此之快，我无法复制整条消息来向您展示整个内容。

啊。公司防病毒控制。

Answer 1

安装 sphinx Python 包后，您有两种选择来执行它，

执行sphinx-build.exe
或执行python -m sphinx

因此，在您确切了解删除前者的具体内容之前，您可以尝试使用后者作为替代方法。

Answer 2

为了清楚地了解我们正在谈论的内容，让我们查看相关列表 file/directories（仅列出与当前案例相关的文件）。

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 and you can see this implemented in Sphinx's setup.py on GitHub.

调用python -m sphinx的解决方案对应如下：

1.1.1. Interface options

-m <module-name>

Package names (including namespace packages) are also permitted. When a package name is supplied instead of a normal module, the interpreter will execute <pkg>.__main__ as the main module.

实际上，通过调用 python -m sphinx，您正在执行 Sphinx 包，就好像它是一个模块一样，如果您在命令行中不带任何参数进行调用，则可以验证这一点，结果将是：

usage: __main__.py [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...] __main__.py: error: the following arguments are required: 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。如果您的项目具有通常的 file/directory 布局 (with source separate from build)，它将如下所示：

C:\Your_Project
├───docs
│    ├──build
│    ├──source
│    ├──make.bat
│    └──makefile
│
├───src
(...)

让我们包括上面的 4 行相关内容 makefile，以便在我们结束解释之前清楚地了解发生了什么：

SPHINXOPTS    ?=
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = source
BUILDDIR      = build

2 个目录 SOURCEDIR 和 BUILDDIR 对应于上面提到的 build 和 source 目录。当您调用 makefile 运行ning make html 时发生的事情是使用以下签名（来自文档）调用 sphinx-build：

sphinx-build

Synopsis

sphinx-build [options] <sourcedir> <outputdir> [filenames …]

可能的解决方案：

解决方案 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 作为脚本调用 Python （更准确地说是 build.py）显式传递完整路径。（同样的方法也适用于其他可执行文件）。

这里需要注意2点：

如果您正在构建 HTML，则 -b 选项是必需的，因此您将在选项列表中传入 -b html。
在 Windows 上，路径分隔符是反斜杠 \ 但您传递给 Sphinx 的参数需要使用正斜杠 / 作为分隔符。

Windows Python: sphinx-build.exe 文件 "disappears"

Windows Python: sphinx-build.exe file "disappears"

python

windows

makefile

python-sphinx