如何在Cython中使用Sphinx？ [英] How do I use Sphinx with Cython?

问题描述

我最近通过将所有模块（顶级 __ init __。py 除外）重命名为 *，来对我的一个项目进行了Cython化。 pyx ，然后将 ext_modules = [Extension（'foo'，['foo.pyx']）] 放入 setup.py 。建造和安装工作正常。但是，当我执行 cd doc时； make html ，Sphinx失败，因为它无法导入现在 *。pyx 的任何模块。

I have recently Cythonized a project of mine by renaming all of the modules (except for the top-level __init__.py) to *.pyx, and by putting ext_modules = [Extension('foo', ['foo.pyx'])] in setup.py. Building and installing works fine. However, when I do cd doc; make html, Sphinx fails because it cannot import any of the modules which are now *.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可以找到所有模块并可以生成文档，但是在那种情况下，在格式化foo.bar的参数时出现诸如 error之类的错误：<内置函数bar>不是Python函数。大概是因为现在Sphinx只能访问 *。so 文件，而不能访问源文件。相同的 sys.path 修改还允许通过Sphinx运行doctest（ make doctest ）。

If I edit doc/conf.py and change sys.path.insert(0, os.path.abspath('..')) to sys.path.insert(0, os.path.abspath('../build/temp.linux-x86_64-2.7')), then Sphinx can find all of the modules and can generate documentation, but in that case I get errors like error while formatting arguments for foo.bar: <built-in function bar> is not a Python function. Presumably this is because now Sphinx only has access to the *.so files, not the source files. That same sys.path modification also allows running the doctests via Sphinx (make doctest).

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

The other solution I tried was using the extension *.py instead of *.pyx (and using ext_modules = [Extension('foo', ['foo.py'])] in setup.py). In this case, the documentation builds correctly, but I think the doctests now bypass Cython.

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

I have not been able to find any information online regarding using Sphinx and Cython together. I have looked at source code for some projects which use both, but they don't seem to make use of docstrings in the *.pyx files. I know that Sage does, but that project is too complicated for me to pick apart.

Sphinx是否支持Cython文件中的文档字符串？如果是这样，我该如何做呢？

Does Sphinx support docstrings in Cython files? If so, how do I make this work?

推荐答案

随意留下更好的答案，但这是我的解决方法已找到。

Feel free to leave a better answer, but here is a fix that I have found.

dipy 项目从 doc / conf手动导入其自己的模块。 py 。这要求首先安装模块，但它可以修复导入错误（doctests将在Cythonized文件上运行）。

The dipy project manually imports their own module from doc/conf.py. This requires that the module first be installed, but it fixes the import errors (and doctests will run on the Cythonized files).

但是，错误格式化参数问题仍然存在。首先，您需要指示Cython将方法/函数签名嵌入到 *。so 文件中。通过设置 embedsignature Cython指令来执行此操作。 dipy 项目在每个 *。pyx 文件中进行设置，但也可以在<$ c中进行设置$ c> setup.py （有关操作方法，请参见Cython文档）。但是，这仍然没有将方法签名放入Sphinx文档中！在此处中有关于方法签名问题的错误报告和补丁。到目前为止，最新版本的Sphinx（1.1.3）仍未包括该功能，但是，如果您从开发库中安装了Sphinx，它将可以使用。

However, the error while formatting arguments problem is still there. First you need to instruct Cython to embed the method/function signatures into the *.so files. Do this by setting the embedsignature Cython directive. The dipy project sets this in each *.pyx file, but it is also possible to set it in setup.py (see Cython documentation for how to do that). This still doesn't put the method signatures into the Sphinx documentation though! There is a bug report and patch for the method signatures problem here. It is still not included in the latest Sphinx release as of now (1.1.3) but if you install Sphinx from the development repo it will work.

这篇关于如何在Cython中使用Sphinx？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！