cython - 如何将 Sphinx 与 Cython 一起使用？

Question

我最近通过将所有模块(顶级 __init__.py 除外)重命名为 *.pyx 来对我的一个项目进行 Cython 化。 ，并通过输入 ext_modules = [Extension('foo', ['foo.pyx'])]在 setup.py .建筑和安装工作正常。然而，当我做 cd doc; make html , Sphinx 失败，因为它无法导入现在为 *.pyx 的任何模块.

如果我编辑 doc/conf.py并更改 sys.path.insert(0, os.path.abspath('..'))至sys.path.insert(0, os.path.abspath('../build/temp.linux-x86_64-2.7')) ，然后 Sphinx 可以找到所有模块并生成文档，但在这种情况下，我会收到类似 error while formatting arguments for foo.bar: <built-in function bar> is not a Python function 的错误.大概这是因为现在 Sphinx 只能访问 *.so文件，而不是源文件。同样的sys.path修改还允许通过 Sphinx (make doctest) 运行文档测试。

我尝试的另一个解决方案是使用扩展名 *.py而不是 *.pyx (并在 ext_modules = [Extension('foo', ['foo.py'])] 中使用 setup.py )。在这种情况下，文档构建正确，但我认为 doctests 现在绕过 Cython。

我无法在网上找到有关一起使用 Sphinx 和 Cython 的任何信息。我查看了一些同时使用两者的项目的源代码，但它们似乎没有使用 *.pyx 中的文档字符串。文件。我知道 Sage 有，但那个项目太复杂了，我无法分清。

Sphinx 是否支持 Cython 文件中的文档字符串？如果是这样，我该如何进行这项工作？

Answer 1

正如 Golgauth 所解释的，Sphinx 的自动文档模块从 .so 获取文档字符串。 ，而不是 .pyx .在对 Python 模块进行 cythonizing 时，无需对 Sphinx 配置进行任何更改即可生成文档的最简单方法是在生成文档之前简单地构建扩展模块:

python setup.py build_ext --inplace

这样，autodoc 将在常规 Python 模块旁边找到扩展模块，并能够按照您的预期生成文档。

为避免忘记此步骤，您可以编辑 Makefile由 sphinx-quickstart 生成在运行 sphinx-build 之前构建扩展模块:

html:
  @cd /path/to/setup.py; python setup.py build_ext --inplace
  ...