Как использовать Sphinx с Cython?

Question

Я недавно разработал проект шахты, переименовав все модули (за исключением верхнего уровня __init__.py) на *.pyx, и положив ext_modules = [Extension('foo', ['foo.pyx'])] в setup.py. Строительно-монтажные работы отлично. Однако, когда я делаю 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')), то Сфинкса можно найти все модули и может генерировать документацию, но в этом случае я получаю ошибки как error while formatting arguments for foo.bar: <built-in function bar> is not a Python function. Предположительно, это потому, что теперь Sphinx имеет доступ только к файлам *.so, а не к исходным файлам. Эта же модификация sys.path также позволяет запускать доктрины через Sphinx (make doctest).

Другое решение я попытался было использовать расширение *.py вместо *.pyx (и используя ext_modules = [Extension('foo', ['foo.py'])] в setup.py). В этом случае документация строит правильно, но я думаю, что доктрины теперь обойти Cython.

Я не был в состоянии найти информацию в Интернете относительно использования Sphinx и Cython вместе. Я посмотрел исходный код для некоторых проектов, которые используют оба варианта, но они, похоже, не используют docstrings в файлах *.pyx. Я знаю, что Sage делает, но этот проект слишком сложный для меня, чтобы разобраться.

Поддерживает ли Sphinx docstrings в файлах Cython? Если да, то как мне это сделать?

Answer 1

Не стесняйтесь оставлять лучший ответ, но вот исправление, которое я нашел.

Проект dipy вручную импортирует собственный модуль с doc/conf.py. Для этого необходимо сначала установить модуль, но он исправляет ошибки импорта (и доктрины будут выполняться в файлах Cythonized).

Однако проблема error while formatting arguments все еще существует. Сначала вам нужно поручить Cython встроить сигнатуры метода/функции в файлы *.so. Сделайте это, установив директиву Cython embedsignature. Проект dipy устанавливает это в каждом файле *.pyx, но его также можно установить в setup.py (см. Документацию Cython о том, как это сделать). Это все еще не помещает сигнатуры метода в документацию Sphinx! Существует отчет об ошибке и исправление для проблемы сигнатур метода here. Он до сих пор не включен в последнюю версию Sphinx (1.1.3), но если вы установите Sphinx из репозитория разработки, он будет работать.

Answer 2

Вы выглядите немного путаным здесь. Sphinx на самом деле не синтаксический анализатор. Ваш код Python должен быть запущен, чтобы Sphinx смог поймать docstrings. Вот почему переименование файлов расширений на «.py» не помогает.

Ну, я недавно работал с Sphinx и Cython и хотел бы поделиться своим опытом ... Вот подробная процедура получения автоматизированной генерации html-документации для данного скомпилированного расширения Cython из docstrings:

[Примечание: Я использовал Sphinx 1.1.3 и Cython 0.17.4]

Прежде всего, используйте питон «строку документацию» (со всеми ограничениями, он может иметь - к примеру, вы не можете описать конструктор.См docstrings спецификации) в коде 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".

Затем запустите «sphinx-quickstart» и ответьте на вопросы. Не забудьте сказать «да», когда его попросят «autodoc». Это создаст файл «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-файлов в каталоге «.../_ build/html /»). Может быть, Сфинкс и Китон развились после того, как был задан предыдущий вопрос, но у меня не было проблем с «сигнатурой». Никакой конкретной директивы Cython для использования или каких-либо исправлений для применения к Sphinx ...

Надеюсь, это поможет.

EDIT: Хорошо, я хотел бы вернуть слова. Я столкнулся с проблемой, которую «Дэн» упоминал в отношении вопроса «embedsignature» при использовании Epydoc (так что я полагаю, что это проблема и для Sphinx). Активация этой директива компилятора не отправляет питон совместимых подписей в любом случае:

PyLabNode.SetNetwork(self, PyLabNetwork net) 

Это имеет 2 недостатка: Пунктирное обозначение класса префикс и типизированный параметр.

В конце концов, единственный способ, которым я мог понять, чтобы послать правильные данные было написать послушную подпись на самой первой линии строк DOC, как так:

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 пользователей ...

---

EDIT: Что касается __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 3

Как объясняет Golgauth модуль автодок Сфинкса принимает из строки документации .so, а не .pyx. Самый простой способ генерации документации без внесения каких-либо изменений в конфигурации Sphinx, когда cythonizing модуль Python является простой сборки модулей расширения на месте, прежде чем генерировать документы:

python setup.py build_ext --inplace 

Таким образом AutoDoc будет найдите модули расширения вместе с регулярными модулями Python и сможете генерировать документацию, как и следовало ожидать.

Чтобы не рисковать забыть этот шаг вы можете редактировать Makefile порожденную sphinx-quickstart строить модули расширения перед запуском sphinx-build:

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