我遇到了同样的问题,发现现在可以在 readthedocs 上编译 Cython 扩展。
简短回答:可以使用 readthedocs 提供的 virtualenv 功能来编译 Cython 模块。
有关稍长的答案和示例项目,请参见下文。
问题是什么?
据我了解,sphinx 导入项目中应记录的所有模块,然后在 python 中提取文档字符串。这对于 Cython 模块来说是失败的,因为它们不能直接导入,必须首先编译。在 readthedocs 上编译模块并不是开箱即用的,但他们提供了一个工具来实现这一点。
怎么解决这个问题。
在 virtualenv 中安装项目时,将构建 Cython 模块(到 .so 文件中),然后可以导入。不过,这可能需要一些外部模块(下面的示例中的 numpy,当然还有 Cython)。这些可以在一个中指定pip 需求文件 (requirements.txt
)它必须位于您的存储库中。
- 启用该选项
install your project inside a virtualenv
under Admin -> 高级设置阅读文档时
- 输入你的路径
requirements.txt
相对于项目根目录(docs/requirements.txt
在下面的例子中)
- (如有必要,更改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 文件。
要解决此问题,只需完全删除该线即可。
我希望这有帮助。