cython - 如何在Cython中使用Sphinx？

最近，我通过将所有模块(顶级__init__.py除外)重命名为*.pyx，并将ext_modules = [Extension('foo', ['foo.pyx'])]放在setup.py中，将Cython归类为我的项目。建造和安装工作正常。但是，当我执行cd doc; make html时，Sphinx失败，因为它无法导入现在为*.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可以找到所有模块并可以生成文档，但是在这种情况下，我会收到类似error while formatting arguments for foo.bar: <built-in function bar> is not a Python function的错误。大概是因为现在Sphinx仅可以访问*.so文件，而不能访问源文件。相同的sys.path修改还允许通过Sphinx(make doctest)运行doctest。

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

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

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

最佳答案

您在这里看起来有点困惑。 Sphinx并不是真正的语法分析器。您的Python代码必须可运行才能使Sphinx能够捕获文档字符串。这就是为什么将扩展文件重命名为“.py”无济于事的原因。

好吧，我最近一直在使用Sphinx和Cython，并希望分享我的经验...这里是完整详细的过程，可从docstrings自动生成给定的Cython扩展名的html文档:

[注意:我使用了Sphinx 1.1.3和Cython 0.17.4]

首先，在您的Cython代码中使用Python的“文档字符串”(具有它的所有限制-例如，您不能描述构造函数。请参见docstrings规范):

cdef class PyLabNode:
    """
    This is a LabNode !!!
    """
    cdef LabNode* thisptr
    cdef PyLabNetwork network

    def __cinit__(self):
       self.thisptr = new LabNode()

    def __dealloc__(self):
       if self.thisptr:
           del self.thisptr

    def SetNetwork(self, PyLabNetwork net):
        """
        Set the network !!!
        """
        self.network = net

并重新编译“yourextension.so”。

然后运行“sphinx-quickstart”并回答问题。当询问“autodoc”时，请不要忘记说是。这将生成“Makefile”，“index.rst”文件和“conf.py”文件。

最后的“conf.py”必须进行编辑以告诉Sphinx要找到您的模块:

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../../parent/dir/of/yourextension/'))

还必须编辑“index.rst”文件以告诉您可以分析哪个模块:

Contents:

.. toctree::
   :maxdepth: 2


.. automodule:: yourextension
   :members:
   :undoc-members:
   :show-inheritance:

最后，通过执行以下操作来构建文档:

$ make html

这对我来说已经足够了(我在“... / _ build / html /”目录中得到了一组html文件)。自问上一个问题以来，可能是Sphinx和Cython进化了，但是我没有“签名”问题要处理。没有特定的Cython指令可以使用，也没有任何适用于Sphinx的修复程序...

希望这可以帮助。

编辑:好吧，我想再说一遍。我在使用Epydoc时遇到了“Dan”提到的有关“嵌入签名”问题的问题(所以我想这也是Sphinx的问题)。无论如何，激活此编译器指令不会发送符合python的签名:

PyLabNode.SetNetwork(self, PyLabNetwork net)

这有两个缺点:类前缀和类型化参数的点分表示法。

最后，我想出的发送正确签名的唯一方法是在文档字符串的第一行写一个兼容的签名，如下所示:

def SetNetwork(self, PyLabNetwork net):
    """
    SetNetwork(self, net)
    Set the net !!!
    @param self: Handler to this.
    @type self: L{PyLabNode}
    @param net: The network this node belongs to.
    @type net: L{PyLabNetwork}
    """
    self.network = net

希望这可以帮助Sphinx和Epydoc用户...

编辑:关于__cinit__，我可以通过将描述加倍来使用Epidoc成功地生成文档(未尝试使用Sphinx)，如下所示:

# For Epydoc only (only used for docstring)
def __init__(self, sim):
    """
    __init__(self, sim)
    Constructor.
    @param sim: The simulator this binding is attached to.
    @type sim: L{PyLabSimulatorBase}
    """

# Real Cython init
def __cinit__(self, PyLabSimulatorBase sim):
   self.thisptr = new LabNetBinding()
   self.sites = []
   simulator = sim

关于cython - 如何在Cython中使用Sphinx？，我们在Stack Overflow上找到一个类似的问题：https://stackoverflow.com/questions/10057476/