Windows Python:sphinxbuild.exe文件“消失”

Question

问题是“为什么Sphinx不能在Windows中工作？”或者“为什么Sphinx-build.exe在正确安装后丢失？”

我有一个答案，在这里

我们使用Sphinx生成Python文档。它在Linux中工作正常，但昨天它在Windows中停止了工作。我见过关于“sphinx build.exe”是一个丢失文件的错误报告

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

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

以下是删除并重新安装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生成失败：

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

我一次又一次地这么做，觉得自己快要发疯了。第八次，我注意到右下角出现了一个警告。这就是原因。“Crowdstrike检测到恶意软件”。这个东西突然出现并消失得如此之快，我无法复制整个消息来向您展示整个事情

啊。公司防病毒控制

Answer 1

为了清楚地了解我们正在谈论的内容，让我们看一下相关文件/目录的列表（仅列出与手头案例相关的文件）

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^{}，您可以在Sphinx's ^{} 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。如果您的项目具有通常的文件/目录布局（with ^{} separate from ^{}），它将如下所示：

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

在我们结束解释之前，让我们包括上述makefile的4行相关内容，以清楚地了解正在发生的事情：

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

这两个目录SOURCEDIR和BUILDDIR对应于上述build和source目录。调用运行make html的makefile时发生的情况是使用以下签名（来自文档）调用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目录调用它）。因此，让我们考虑2个可能的路径，在不使用MaFix::/P>时从哪里调用。

• 从/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

这归结为使用^{}作为脚本调用Python（更准确地说^{），显式地传递完整路径。（同样的方法也适用于其他可执行文件）

这里需要注意两个重要事项：

1. 如果您正在构建HTML，^{}选项是必需的，因此您将在选项列表中传入-b html

2. 在Windows上，路径分隔符是反斜杠\，但传递到Sphinx的参数需要使用前斜杠/作为分隔符

Answer 2

安装sphinx Python包后，有两个选项可以执行它

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

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