Windows Python:sphinx-build.exe 文件“消失" [英] Windows Python: sphinx-build.exe file "disappears"
问题描述
问题是为什么 Sphinx 不能在 Windows 中运行?";或为什么在正确安装后缺少 sphinx-build.exe?".
The question is "why won't Sphinx work in Windows?" or "why is sphinx-build.exe missing after a proper install?".
我有一个答案，就在这里.
I have one answer, here it is.
我们使用 Sphinx 生成 Python 文档.它在 Linux 中运行良好，但昨天它在 Windows 中停止工作.我看过关于sphinx-build.exe"的错误报告.是一个丢失的文件.
We use Sphinx to generate Python docs. It works fine in Linux, but yesterday it stopped working in Windows. I've seen bug reports about "sphinx-build.exe" being a missing file.
我今天在 Windows 系统上找到了问题的根源.问题的症状是可执行文件sphinx-build.exe"失败后从文件系统中消失.
I got to the bottom of the problem today on a Windows system. The symptom of the problem is that an executable "sphinx-build.exe" vanishes from the file system after a failed make.
我已经多次重复这个循环.如果我在虚拟环境中也会发生同样的情况
I've repeated this cycle several times. Same happens if I am in a virtual environment
这是我删除并重新安装 Sphinx 后的 Scripts 目录:
Here is my Scripts directory after removing and re-installing 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 失败:
An attempt to run sphinx-build fails:
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>
之后，列表显示文件已消失:
After that, the listing shows the file has disappeared:
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 检测到恶意软件".东西突然弹出又消失得如此之快，我无法复制整个消息来向你展示整个事情.
I did this over and over, thinking I was going crazy. On the 8th time, I noticed a warning was coming up just for a moment on the bottom right. This explained it. "Crowdstrike detected malicious software". The thing pops up and disappears so quickly I cannot copy down whole message to show you whole thing.
啊.企业防病毒控制.
推荐答案
为了清楚地了解我们正在谈论的内容，让我们查看相关文件/目录的列表(只有与手头案例相关的文件才会出现).
To get a clear picture of what we're talking about lets look at the list of relevant file/directories (only files relevant to the case at hand are featured).
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 你可以在 GitHub 上的 Sphinx setup.py.
Now, the executable .exe files (that your anti-virus is deleting) are basically mappings to the corresponding .py modules (all featured above). These are the equivalent to setuptools entry_points and you can see this implemented in Sphinx's setup.py on GitHub.
调用python -m sphinx的解决方法对应如下:
The solution of calling python -m sphinx corresponds to the following:
1.1.1.界面选项
包名称(包括命名空间包)也是允许的.当提供包名而不是普通模块时，解释器将执行 <pkg>.__main__ 作为主模块.
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 包，就好像它是一个模块一样，如果您在命令行上不带任何参数进行调用，则可以验证这一点，结果将是:
In reality by calling python -m sphinx you are executing the Sphinx package as if it were a module, this can be verified if you make the call without any arguments on the command line, the result would be:
用法:__main__.py [OPTIONS] SOURCEDIR OUTPUTDIR [文件名...]__main__.py:错误:需要以下参数:sourcedir、outputdir、filenames
usage: __main__.py [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...] __main__.py: error: the following arguments are required: sourcedir, outputdir, filenames
那么让我们看看上面特色的 __main__.py 文件的内容:
So lets look at the contents of the above featured __main__.py file:
import sys
from sphinx.cmd.build import main
sys.exit(main(sys.argv[1:]))
这就是我写一个更广泛的答案(也为未来的读者)的原因，因为如果你的防病毒软件决定同时删除 sphinx-apidoc.exe 和 sphinx-quickstart.exe 仅仅使用 python -m sphinx 不会解决这些进一步的问题.
This is the reason I'm writing a more extensive answer (also for future readers), because if your anti-virus decides to also delete sphinx-apidoc.exe and sphinx-quickstart.exe simply using python -m sphinx won't solve those further problems.
最后，当您运行 make html 时，您正在执行(很可能)使用 sphinx-quickstart 生成的 makefile.如果您的项目具有通常的文件/目录布局(与 source 与 build 分开)它看起来像这样:
Finally, when you run make html you are executing the makefile that was (most likely) generated using sphinx-quickstart. If your project has the usual file/directory layout (with source separate from build) it will look like this:
C:\Your_Project
├───docs
│ ├──build
│ ├──source
│ ├──make.bat
│ └──makefile
│
├───src
(...)
让我们包含上述 makefile 的 4 行相关行，以便在我们结束解释之前清楚地了解正在发生的事情:
Lets include the 4 relevant lines of the above makefile to get a clear picture of what's happening before we wrap-up the explanation:
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
这两个目录SOURCEDIR 和BUILDDIR 对应于上面提到的build 和source 目录.当您调用运行 make html 的 makefile 时会发生什么正在使用以下签名(来自文档)调用 sphinx-build:
The 2 directories SOURCEDIR and BUILDDIR correspond to the build and source directories featured above. What is happening when you invoke the makefile running make html is invoking sphinx-build with the following signature (from the documentation):
概要
sphinx-build [选项]
sphinx-build [options] <sourcedir> <outputdir> [filenames …]
可能的解决方案:
解决方案 1.您可以将对应于 SPHINXBUILD ?= sphinx-build 的行更改为 SPHINXBUILD ?= python -m sphinx 它将起作用并且您将执行 sphinx 包 作为模块(如__main__.py 文件所示).
Solution 1. You can change the line corresponding to SPHINXBUILD ?= sphinx-build to SPHINXBUILD ?= python -m sphinx it will work and you'll be executing the sphinx package as a module (as shown by the __main__.py file).
但是如果您的防病毒软件决定删除剩余的可执行 .exe 文件(并且您还想执行那些).此外，在很多情况下您都希望完全避免使用 makefile，因此给出完整的解释可以解决所有这些情况.
But that doesn't solve (nor address) the potential problem if your anti-virus decides to delete the remaining executable .exe files (and you also want to execute those). Besides, there are a number of scenarios where you'll want to avoid using the makefile altogether, so giving the full explanation addresses all these scenarios.
解决方案 2.您可以直接使用 Sphinx 进行构建，无需可执行文件或 makefile.
Solution 2. You can build with Sphinx directly without the executable or the makefile.
当您调用 make html 时，您通常会在包含 makefile 的路径上执行此操作(在上面的示例中，您将从 /docs 目录中调用它).因此，让我们考虑在不使用 makefile 时从何处调用的 2 条可能路径:
When you call make html you usually do so on the path that has the makefile (in the above examples you'd call it from the /docs directory). So lets consider 2 possible paths from where to invoke when not using the makefile:
从
/docs目录调用.您可以传递与执行位置相关的source和build目录，如下所示:
Calling from the
/docsdirectory. You can pass thesourceandbuilddirectories relative to where you're executing, like this:
python C:\PATH_TO_YOUR_VENV_OR_INSTALLATION\Lib\site-packages\sphinx\cmd\build.py -b html source build/html
从任何地方呼叫.您可以像这样使用 source 和 build 的完整路径:
Calling from anywhere. You'd use full paths for source and build like this:
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
这归结为使用 调用 Pythonsphinx-build 作为脚本(更准确地说是build.py)明确传递完整路径.(同样的方法也适用于其他可执行文件).
Which boils down to calling Python with sphinx-build as a script (more precisely build.py) passing in the full paths explicitly. (And the same method would also apply for the other executables).
这里有两个重要的注意事项:
Here 2 important notes are necessary:
如果您正在构建 HTML，
-b选项是必要的，因此您将在选项列表中传入-b html.
在 Windows 上，路径分隔符是反斜杠 \ 但是你传递给 Sphinx 的参数需要使用正斜杠 / 作为分隔符.
On Windows the path separators are backslashes \ but the arguments you are passing into Sphinx need to use forwardslashes / as separators.
这篇关于Windows Python:sphinx-build.exe 文件“消失"的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
