如何使用狮身人面像用Cython？(How do I use Sphinx with Cython?

我最近Cythonized我的一个项目，通过重命名所有模块（除了顶级__init__.py ），以*.pyx ，并通过把ext_modules = [Extension('foo', ['foo.pyx'])]在setup.py 。 建筑及安装工作正常。 然而，当我做cd doc; make html cd doc; make html ，狮身人面像，因为它无法导入任何现属模块的失败*.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'))然后狮身人面像可以找到所有的模块，并且可以生成文档，但在这种情况下，我得到这样的错误error while formatting arguments for foo.bar: <built-in function bar> is not a Python function 。 据推测，这是因为现在的狮身人面像只获得了*.so文件，没有源文件。 同样sys.path修改还允许通过狮身人面像（运行的doctests make doctest ）。

我尝试其他溶液使用扩展*.py代替*.pyx （和使用ext_modules = [Extension('foo', ['foo.py'])]在setup.py ）。 在这种情况下，文档建立正确，但我认为现在文档测试绕过用Cython。

我一直没能找到使用狮身人面像，并用Cython一起有关的任何信息网上。 我已经看过了其中同时使用一些项目的源代码，但似乎他们不利用文档字符串中的*.pyx文件。 我知道，贤者的做法，但这个项目太复杂，我挑开。

狮身人面像是否支持文档字符串在用Cython文件？ 如果是这样，我该如何使这项工作？

Answer 1:

你看这里豆蔻位混淆。 斯芬克斯是不是一个真正的句法分析器。 Python代码必须是可运行的，使狮身人面像能够赶上文档字符串。 这就是为什么重命名扩展名的文件，以“py”为于事无补。

嗯，我一直与狮身人面像和用Cython近日，并且想和大家分享我的经验......下面是完整的详细过程，以获得自动生成从文档字符串指定编译用Cython扩展名的HTML文档的：

[注：我使用的狮身人面像1.1.3和用Cython 0.17.4]

首先，使用Python的“文档字符串”（所有的限制也多了-通过例如，你无法用语言形容构造见。 文档字符串规范）在用Cython代码：

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”。

然后运行“狮身人面像 - 快速入门”并回答问题。 不要忘了，当问“车博士”说的是。 这会产生“Makefile文件”，在“index.rst”文件和“conf.py”文件。

这最后一个“conf.py”已被编辑告诉狮身人面像被找到你的模块：

# 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

这是足以让我（我得到的结果集的HTML文件中“... / _编译/ HTML /”目录）。 可能是狮身人面像和用Cython已经演变自上次有人问，但我没有“签名”的问题来处理。 没有特别的用Cython指令使用，也没有任何补丁应用到狮身人面像...

希望这可以帮助。

编辑：嗯，我想带着我背单词。 我遇到的问题，“丹”被提同时使用epydoc的关于“embedsignature”物质（所以我想这是狮身人面像的问题，也是）。 激活此编译器指令不反正送蟒符合签名：

PyLabNode.SetNetwork(self, PyLabNetwork net)

这有2个缺点：对于类的前缀和输入参数的点号。

最后，我能想出发送正确的人的唯一办法是在文档字符串像这样的第一行写一个兼容的签名：

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

希望这能帮助这两个狮身人面像和epydoc的用户...

---

编辑：关于__cinit__ ，我能够与成功生成文档Epidoc （不与狮身人面像试图）通过加倍的描述，就像这样：

# 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

Answer 2:

欢迎留下一个更好的答案，但这里是我已经找到了解决。

该dipy项目手动导入自己的模块doc/conf.py 。 这就要求模块首先进行安装，但修复导入错误（和文档测试将在Cythonized文件运行）。

然而， error while formatting arguments的问题依然存在。 首先，你需要指示用Cython的方法/函数签名嵌入到*.so文件。 通过设置这样做embedsignature用Cython指令。 该dipy项目中的每个设置此*.pyx文件，但它也可以将其设置在setup.py （见如何做到这一点用Cython文档）。 这仍然没有把方法签名到狮身人面像的文档，但！ 没有为方法签名问题，bug报告和补丁这里 。 它仍然是不包含在最新的狮身人面像发布，截至目前（1.1.3），但如果从发展回购安装狮身人面像它会工作。

Answer 3:

作为Golgauth解释说，狮身人面像的车博士模块从取文档字符串.so ，不是.pyx 。 没有cythonizing一个Python模块时不必进行任何更改到您的狮身人面像的配置产生你的文档的最简单的方法就是简单的构建到位的扩展模块在生成文档之前：

python setup.py build_ext --inplace

车博士这样就会发现常规的Python模块旁边的扩展模块，将能够产生如你所期望的文档。

要不要冒险忘记你可以编辑这个步骤Makefile所产生的sphinx-quickstart建立运行之前的扩展模块sphinx-build ：

html:
  @cd /path/to/setup.py; python setup.py build_ext --inplace
  ...

文章来源: How do I use Sphinx with Cython?