Python-C-Extension上的Sphinx autodoc功能 [英] Sphinx autodoc functionality on Python-C-Extension

问题描述

我很难将Sphinx autodoc 功能与我的Python C Extension配合使用。这是甚么可能与狮身人面像？我应该使用其他工具吗？

I'm having a difficult time getting the Sphinx autodoc functionality to work with my Python C Extension. Is this even possible with Sphinx? Should I be using another tool?

我无法找到有关这方面的信息。只是这个（通过autodoc为C Python模块的Sphinx文档） ，但是这个问题没有得到答复。

I haven't been able to find any information on doing this. Just this (Sphinx documentation via autodoc for C Python modules), but that question went unanswered.

我可以使用Python代码为Sphinx autodoc做美丽的事情，但是我无法弄清楚如何用我的C文件。

I can make Sphinx autodoc do beautiful things for me with Python code, but I can't figure out how to replicate the success with my C files.

推荐答案

为了做到这一点，你的C扩展类型对象应该有一个描述它们的文档字符串（PyTypeObject。 tp_doc），方法（PyMethodDef）也应该包含文档字符串。

In order to do that, your C extension type objects should have a doc string that describes them (PyTypeObject.tp_doc) and the methods (PyMethodDef) should include a doc string as well.

    {"go_do_stuff",
    (PyCFunction) Foo_Go_Do_Stuff, METH_VARARGS | METH_KEYWORDS,
    "The way to get stuff done."},

Python C扩展通常用包装文件打包成一个蛋，动态加载它。确保首先 pip install 它。然后，您需要将包含该加载器的目录添加到Sphinx sys.path。编辑您的 conf.py ：

A Python C extension usually comes packaged as an egg with a wrapper file that dynamically loads it. Make sure to first pip install it. Then, you need to add the directory containing that loader to your Sphinx sys.path. Edit your conf.py:

sys.path.append(os.path.abspath('/usr/local/lib/python2.7/site-packages/foo-0.9.99-py2.7-macosx-10.9-x86_64.egg/'))

这将是包含加载器 foo.py 的路径：

This would be the path that includes the loader foo.py:

def __bootstrap__():
  global __bootstrap__, __loader__, __file__
  import sys, pkg_resources, imp
  __file__ = pkg_resources.resource_filename(__name__, 'foo.so')
  __loader__ = None; del __bootstrap__, __loader__
  imp.load_dynamic(__name__,__file__)
__bootstrap__()

现在您可以使用以下声明创建一个 foo.rst ：

Now you can create a foo.rst with the following declaration:

***************************************************
:mod:`foo` --- Foo Client
***************************************************

.. automodule:: foo
   :synopsis: Foo client.
   :members:

当您运行Sphinx时，文档字符串将被记录。

When you run Sphinx the doc strings will get documented.

这篇关于Python-C-Extension上的Sphinx autodoc功能的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！