我最近通过将所有模块(顶级 __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 文件中的文档字符串?如果是这样,我该如何进行这项工作?
最佳答案
正如 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
...
关于cython - 如何将 Sphinx 与 Cython 一起使用?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/10057476/