如何让 Sphinx 在未联网的 Windows 7 计算机上与 Jython 一起工作？

Question

一旦sphinx-apidoc 已经运行，命令C:\path\to\doc\make html 开始产生错误：

找不到“sphinx-build”命令 [snip]

但是该命令确实存在并且设置了相关的环境变量。

更多细节：

1 - 尝试运行 sphinx_apidoc:

'C:\path\to\jython\bin\sphinx-apidoc' 未被识别为内部或外部命令

2 - 使用 Jython 调用有效：jython C:\path\to\jython\bin\sphinx-apidoc 带有合理选项会生成文档 *.rst 文件、conf.py 等文件。

3 - make html 然后产生以下错误：

找不到“sphinx-build”命令 [snip]

然后建议设置SPHINXBUILD 环境变量，甚至设置PATH。我已经设置了这两个环境变量，通过调用echo %PATH% 和echo %SPHINXBUILD% 向自己证明了这一点。

这就是我卡住的地方。 Sphinx 使用的文件（在这种情况下为 sphinx-apidoc 和 sphinx-build）似乎在 C:\path\to\jython\bin\ 目录中，没有任何文件后缀。当直接从 Jython 调用时，它们会按预期工作（参见上面的第 2 点），但是当作为另一个进程的一部分（例如 make html）调用时，它们不会被识别并且执行失败（参见上面的第 1 点和第 3 点）。

有谁知道这个问题是什么、为什么以及最重要的是“如何解决”这个问题？

我的设置过程是在未联网的 Windows 7 计算机上进行的。 Jython (2.5.2) 是使用 Jython 安装程序安装的。然后通过在本地解压并在其解压目录中运行jython setup.py install 来安装以下每个包（setuptools 除外）：

1. setuptools：通过在同一目录中调用jython ez_setup.py 和 setuptools-1.4.2.tar.gz（因此不会尝试下载它）
2. Jinja2 (2.5)
3. docutils (0.11)
4. Pygments (1.6)
5. 狮身人面像 (1.2.1)
6. numpydoc (0.4) - 只提到它是因为它也安装在机器上。

Answer 1

我已经设法让它工作了。问题在于手动安装和使用 Jython 意味着某些预期的环境变量没有到位。此外，使用 Windows 7（我相信一般是 MS Windows）意味着没有扩展的 Python 脚本如果不通过 Jython 显式调用它们就无法运行（Windows 不检查 shebangs）。最后，文件关联尚未设置（安装 CPython 时会自动发生，但 Jython 未设置）。

对于其他有类似问题的人，以下设置适用于我：

地点：

• Java 运行时：C:\Java\jre7
• Jython：C:\Jython\jython2.5.2

用户环境变量：

• JRE_HOME: C:\Java\jre7
• JAVA_HOME: %JRE_HOME%
• 类路径：.
• JYTHON_HOME: C:\Jython\jython2.5.2
• 路径：%JRE_HOME%\bin;%JYTHON_HOME%\bin

文件关联：

• 在命令提示符处键入 assoc .py=Python.File 以将“Python.File”与“.py”扩展名相关联。
• 在命令提示符处键入 ftype Python.File=C:\Jython\jython2.5.2\jython.bat "%1" %* 以将 Jython 命令与“Python.File”类型的文件相关联。
• 将 '.py' (;.PY) 附加到 PATHEXT 系统环境变量。这将使执行 Python 文件成为可能，而无需提供它们的 '.py' 扩展名。 （注意，这无法运行没有“.py”扩展名的 Python 文件。）

文件扩展名：

• 重命名四个 Sphinx 命令以包含“.py”扩展名。这对于 vanilla Windows 7 来说非常困难，因为它尽其所能将用户与文件扩展名等“低级”细节保持距离，但是命令提示符下的重命名命令可以完成这项工作：在 Jython bin 中键入 ren sphinx* sphinx*.py目录。

现在应该可以从任何地方拨打sphinx-apidoc 或类似电话。完成此操作后，从文档目录调用命令 make html 时，应该会按预期工作。