python - 如何在 readthedocs 上记录 cython 函数

Question

关于 ReadTheDocs我不允许编译 cython 扩展，是否可以配置 sphinx 以便从 cython 文件中提取文档字符串而不实际编译它们？

谢谢!

Answer 1

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

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

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

问题是什么？

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

如何解决。

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

1. 在 Admin 下启用选项 install your project inside a virtualenv -> Advanced Settings on readthedocs
2. 输入您的 requirements.txt 相对于项目根目录的路径(下例中的 docs/requirements.txt)
3. (如有必要，更改 python 解释器版本)

现在，每次构建文档时都会安装您的项目(使用 python setup.py install)。如果您在 readthedocs 的 Builds 选项卡中单击相应的构建，则可以在 Setup Output 下看到设置脚本的输出。这是可能出现编译时错误的地方。请注意，编译您的项目可能需要一些时间。

示例项目

一个 Python 包，由几个 Cython 模块组成，每个模块都有 Google-style docstrings .

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
...

按照建议添加到我的 conf.py here .这解决了我在本地构建时的问题(我使用 python setup.py build_ext --inplace 编译了我的项目)，但是在 virtualenv 中安装时，这指向了错误版本的 my_package(即源代码) ，而不是已安装的包)。 sphinx 找不到任何要导入的 .so 文件。

要解决这个问题，只需完全删除该行即可。

希望对您有所帮助。