如何在Python文件无法编译时使用Sphinx自动文档生成

Question

今天这个问题更难了，因为我在Sphinx主页上搜索时运气不好，没找到想要的东西。

我有一组模块想要从文档字符串中生成文档。但是这些模块不是纯粹的Python脚本。它们不能直接编译，因为它们是从一个C#应用程序中运行的，这个应用程序会在执行的环境中创建一个新的变量。

对Python编译器来说，这就像我有一个未定义的方法（实际上确实是这样，直到C#创建了IronPython脚本引擎并定义了这个方法）。

当我运行：

sphinx-build -b html output/html

我得到：

NameError: name 'injected_method' is not defined

我该怎么让Sphinx忽略编译错误，直接生成我的文档呢？

编辑：

如果有人知道有没有其他工具可以替代Sphinx（比如Epydoc），而且不需要编译Python脚本就能获取函数签名和文档字符串，那就太好了。Sphinx是最美观的文档生成工具，但如果必须的话，我也会放弃它。

Answer 1

也许你可以把injected_method定义成一个空函数，这样文档就能正常工作了。你需要确保你注入的injected_method的定义是在新的injected_method占位符之后。

#By empty function I mean a function that looks like this
def injected_method():
  pass

Answer 2

好吧，你可以试试：

• 把使用 injected_method 的部分放在一个 try/except 里，这样可以捕捉到可能出现的错误。
• 写一个脚本，过滤掉所有在导入时运行的 Python 代码，然后把结果传给 Sphinx。
• 你还可以……好吧，我想不出其他办法了。 :)

Answer 3

好的，我找到了一种解决错误的方法。

在设置嵌入式脚本环境时，我不再使用：

ScriptScope.SetVariable("injected_method", myMethod);

而是现在使用：

ScriptRuntime.Globals.SetVariable("injected_method", myMethod);

然后，在脚本中：

import injected_method

接着，我在我的搜索路径中创建了一个空的 dummy injected_method.py 文件。在我构建 C# 项目时，我会删除这个空文件，以避免任何冲突。