如何在 readthedocs 上记录 cython 函数

On 阅读文档我不被允许编译cython扩展，是否可以配置sphinx为了从中提取文档字符串cython文件而不实际编译它们？

thanks!

我遇到了同样的问题，发现现在可以在 readthedocs 上编译 Cython 扩展。

简短回答：可以使用 readthedocs 提供的 virtualenv 功能来编译 Cython 模块。

有关稍长的答案和示例项目，请参见下文。

问题是什么？

据我了解，sphinx 导入项目中应记录的所有模块，然后在 python 中提取文档字符串。这对于 Cython 模块来说是失败的，因为它们不能直接导入，必须首先编译。在 readthedocs 上编译模块并不是开箱即用的，但他们提供了一个工具来实现这一点。

怎么解决这个问题。

在 virtualenv 中安装项目时，将构建 Cython 模块（到 .so 文件中），然后可以导入。不过，这可能需要一些外部模块（下面的示例中的 numpy，当然还有 Cython）。这些可以在一个中指定pip 需求文件 (requirements.txt）它必须位于您的存储库中。

1. 启用该选项install your project inside a virtualenv under Admin -> 高级设置阅读文档时
2. 输入你的路径requirements.txt相对于项目根目录（docs/requirements.txt在下面的例子中）
3. （如有必要，更改python解释器版本）

现在您的项目将被安装（使用python setup.py install）每次构建文档时。设置脚本的输出可以在下面看到设置输出如果您单击相应的构建Builds阅读文档上的选项卡。这就是编译时错误可能出现的地方。请注意，编译您的项目可能需要一些时间。

示例项目

一个由多个 Cython 模块组成的 Python 包，每个模块都有Google 风格的文档字符串.

my_project/
    setup.py
    my_package/
        __init__.py   # imports Cython modules
        cython_module1.pyx
        cython_module2.pyx
        ...
    docs/
        requirements.txt
        Makefile
        source/
            conf.py
            index.rst
            ... #  more documentation

要求.txt

cython>=0.20
numpy>=1.9

注意事项

在我的项目上尝试此操作时，我遇到了无法导入 Cython 模块的问题。 sphinx的错误信息如下：

home/docs/checkouts/readthedocs.org/user_builds/... :4: WARNING: autodoc: failed to import module 'cython_module1';...
File "/home/docs/checkouts/readthedocs.org/user_builds/.../__init__.py", ...
from .cython_module1 import CythonClass

发生这种情况是因为我曾经在本地构建文档并添加了类似的行

...
sys.path.insert(0, os.path.abspath('../../')) # path to my_package
...

to my conf.py按照建议here。这解决了我在本地构建时的问题（我使用python setup.py build_ext --inplace），但是在 virtualenv 中安装时，它指向 my_package 的错误版本（即源，而不是已安装的包）。 sphinx 找不到任何要导入的 .so 文件。

要解决此问题，只需完全删除该线即可。

我希望这有帮助。