<p>为了清楚地了解我们正在谈论的内容,让我们看一下相关文件/目录的列表(仅列出与手头案例相关的文件)</p>
<pre class="lang-none prettyprint-override"><code>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
</code></pre>
<p>现在,可执行的<code>.exe</code>文件(您的反病毒程序正在删除)基本上是映射到相应的<code>.py</code>模块(以上所有功能)。这些等价于setuptools<a href="https://setuptools.readthedocs.io/en/latest/userguide/quickstart.html?entry-points-and-automatic-script-creation#entry-points-and-automatic-script-creation" rel="nofollow noreferrer">^{<cd3>}</a>,您可以在<a href="https://github.com/sphinx-doc/sphinx/blob/3.x/setup.py#L234" rel="nofollow noreferrer">Sphinx's ^{<cd4>} on GitHub</a>中看到它的实现</p>
<p>调用<code>python -m sphinx</code>的解决方案对应于以下内容:</p>
<blockquote>
<p>1.1.1. Interface options</p>
<p><a href="https://docs.python.org/3/using/cmdline.html#cmdoption-m" rel="nofollow noreferrer">-m <module-name></a></p>
<p>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.</p>
</blockquote>
<p>实际上,通过调用<code>python -m sphinx</code>您正在执行Sphinx包,就像它是一个模块一样,如果您在命令行上没有任何参数的情况下进行调用,则可以验证这一点,结果将是:</p>
<blockquote>
<p>usage: __main__.py [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]
__main__.py: error: the following arguments are required: sourcedir, outputdir, filenames</p>
</blockquote>
<p>因此,让我们看一下上述特色<code>__main__.py</code>文件的内容:</p>
<pre class="lang-py prettyprint-override"><code>import sys
from sphinx.cmd.build import main
sys.exit(main(sys.argv[1:]))
</code></pre>
<p>这就是为什么我要写一个更广泛的答案(也是为了将来的读者),因为如果你的反病毒软件决定同时删除<code>sphinx-apidoc.exe</code>和<code>sphinx-quickstart.exe</code>,那么仅仅使用<code>python -m sphinx</code>将无法解决这些进一步的问题</p>
<p>最后,当您运行<code>make html</code>时,您正在执行(很可能)使用<code>sphinx-quickstart</code>生成的makefile。如果您的项目具有通常的文件/目录布局(<a href="https://www.sphinx-doc.org/en/master/man/sphinx-quickstart.html#cmdoption-sphinx-quickstart-sep" rel="nofollow noreferrer">with ^{<cd13>} separate from ^{<cd14>}</a>),它将如下所示:</p>
<pre class="lang-none prettyprint-override"><code>C:\Your_Project
├───docs
│ ├──build
│ ├──source
│ ├──make.bat
│ └──makefile
│
├───src
(...)
</code></pre>
<p>在我们结束解释之前,让我们包括上述<code>makefile</code>的4行相关内容,以清楚地了解正在发生的事情:</p>
<pre class="lang-none prettyprint-override"><code>SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
</code></pre>
<p>这两个目录<code>SOURCEDIR</code>和<code>BUILDDIR</code>对应于上述<code>build</code>和<code>source</code>目录。调用运行<code>make html</code>的<code>makefile</code>时发生的情况是使用以下签名(来自文档)调用<code>sphinx-build</code>:</p>
<blockquote>
<p><a href="https://www.sphinx-doc.org/en/master/man/sphinx-build.html" rel="nofollow noreferrer">sphinx-build</a></p>
<p>Synopsis</p>
<p>sphinx-build [options] <sourcedir> <outputdir> [filenames …]</p>
</blockquote>
<p>可能的解决办法:</p>
<p><strong>解决方案1</strong>。您可以将对应于<code>SPHINXBUILD ?= sphinx-build</code>的行更改为<code>SPHINXBUILD ?= python -m sphinx</code>它将起作用,并且您将作为模块执行sphinx包<strong>(如<code>__main__.py</code>文件所示)</p>
<p><strong>但是</strong>如果您的反病毒软件决定删除剩余的可执行文件<code>.exe</code>(并且您还想执行这些文件),那么这并不能解决(也不能解决)潜在的问题<strong>除了</strong>,还有许多场景需要避免完全使用makefile,因此给出完整的解释可以解决所有这些场景</p>
<p><strong>解决方案2</strong>。您可以直接使用Sphinx构建,而无需可执行文件或makefile</p>
<p>调用<code>make html</code>时,通常在包含makefile的路径上执行(在上面的示例中,您可以从<code>/docs</code>目录调用它)。因此,让我们考虑2个可能的路径,在不使用MaFix::/P>时从哪里调用。
<ul>
<li><p>从<code>/docs</code>目录调用。您可以传递与执行位置相关的<code>source</code>和<code>build</code>目录,如下所示:</p>
<p><code>python C:\PATH_TO_YOUR_VENV_OR_INSTALLATION\Lib\site-packages\sphinx\cmd\build.py -b html source build/html</code></p>
</li>
<li><p>从任何地方打电话。对<code>source</code>和<code>build</code>使用完整路径,如下所示:</p>
<p><code>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</code></p>
</li>
</ul>
<p>这归结为使用<a href="https://www.sphinx-doc.org/en/master/man/sphinx-build.html#sphinx-build" rel="nofollow noreferrer">^{<cd22>}</a><strong>作为脚本调用Python(更准确地说^{<cd37>),显式地传递完整路径。(同样的方法也适用于其他可执行文件)</p>
<p>这里需要注意两个重要事项:</p>
<ol>
<li><p>如果您正在构建HTML,<a href="https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-b" rel="nofollow noreferrer">^{<cd38>}</a>选项是必需的,因此您将在选项列表中传入<code>-b html</code></p>
</li>
<li><p>在Windows上,路径分隔符是反斜杠<code>\</code>,但传递到Sphinx的参数需要使用前斜杠<code>/</code>作为分隔符</p>
</li>
</ol>