如何在readthedocs上记录cython函数

问题描述

在上，我无法编译 cython 扩展名，是否可以配置 sphinx 以便从 cython 文件中提取文档字符串而无需实际编译它们？

On ReadTheDocs I am not allowed to compile cython extensions, is it possible to configure sphinx in order to extract the docstrings from the cython files without actually compiling them?

谢谢！

推荐答案

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

I faced the same problem and found that it is possible now to compile Cython extensions on readthedocs.

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

Short answer: Cython modules can be compiled using the virtualenv feature provided by readthedocs.

答案稍长，示例项目见下文。

For a slightly longer answer and an example project see below.

据我所知sphinx导入了项目中应记录的所有模块，然后在python中提取了文档字符串。对于Cython模块，此操作将失败，因为它们无法直接导入，必须先进行编译。编译模块在readthedocs上不是开箱即用的，但是它们提供了实现此目的的工具。

As I have understood it, sphinx imports all modules of the project that shall be documented and then extracts the docstrings in python. This fails for Cython modules, as they cannot be directly imported and have to be compiled first. Compiling the modules does not work out of the box on readthedocs, but they are providing a tool to realise this.

在virtualenv中安装项目时，将构建Cython模块（.so文件），然后可以将其导入。不过，这可能需要一些外部模块（以下示例为numpy，当然也包括Cython）。可以在（要求.txt ）。

When installing the project in a virtualenv, the Cython modules will be build (into .so files) and can then be imported. This might require some external modules though (numpy for the example below and, of course, Cython). These can be specified in a pip requirements file (requirements.txt) that has to be in your repository.

1. 启用选项 install您的项目在readthedocs上 Admin -> Advanced Settings 下的virtualenv 中


2. 输入您的路径相对于项目根目录的 requirements.txt （在下面的示例中为 docs / requirements.txt ）


3. （如有必要，请更改python解释器版本）

1. Enable the option install your project inside a virtualenv under Admin -> Advanced Settings on readthedocs
2. Enter the path to your requirements.txt relative to the project root (docs/requirements.txt in the example below)
3. (If necessary change the python interpreter version)

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

Now your project will be installed (using python setup.py install) each time the documentation is build. The output of the setup script can be seen under Setup Output if you click on the respective build in the Builds tab on readthedocs. This is where compile time errors might show up. Mind that compiling your project might take some time.

由多个Cython模块组成的Python程序包，每个都有。

A Python package consisting of several Cython modules, each of which has 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

requirements.txt

cython>=0.20
numpy>=1.9

Caveat（s）

在我的项目中尝试此操作时，我遇到了我的Cython模块的问题无法导入。狮身人面像的错误消息显示为：

Caveat(s)

While trying this on my project I ran into the problem that my Cython modules could not be imported. The error message of sphinx read like:

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

发生这种情况是因为我以前在本地构建文档并添加了一行例如

This happened, because I used to build my documentation locally and had added a line like

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

我 conf.py 作为建议的。这已经解决了我在本地构建时的问题（我在其中使用 python setup.py build_ext --inplace 编译项目），但是在virtualenv中安装时却指向错误的版本my_package（即来源，而不是已安装的软件包）。没有狮身人面像找不到要导入的.so文件。

to my conf.py as suggested here. This had solved my problem when building locally (where I compiled my project using python setup.py build_ext --inplace), but when installing in the virtualenv this points to the wrong version of my_package (namely the sources, not the installed package). There sphinx can not find any .so files to import.

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

To solve this, just remove the line completely.

我希望这会有所帮助。

这篇关于如何在readthedocs上记录cython函数的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！