Вопрос по – Как мне использовать Sphinx с Cython?

15

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

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

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

Поддерживает ли Sphinx строки документации в файлах Cython? Если так, как я могу заставить это работать?

Просто примечание, может быть, вы можете попробоватьopendreamkit.org/2017/06/09/CythonSphinx Только что попробовал сам, похоже на работу. xxks-kkk

Ваш Ответ

3   ответа
7

Ты выглядишь немного смущенным здесь. Сфинкс на самом деле не синтаксический анализатор. Ваш код Python должен быть запущен, чтобы Sphinx мог перехватывать строки документов. Вот почему переименование файлов расширений в & quot; .py & quot; не помогает.

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

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

Прежде всего, используйте Python & lt; s & quot; docstrings & quot; (со всеми возможными ограничениями - например, вы не можете описать конструктор. См.строки документации спецификации) в вашем коде 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». файл и файл & quot; conf.py & quot; файлы.

Этот последний "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/'))

& Quot; index.rst & quot; Файл также должен быть отредактирован, чтобы указать, какой модуль может быть проанализирован:

Contents:

.. toctree::
   :maxdepth: 2


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

Наконец, соберите документацию, выполнив:

$ make html

Для меня этого было достаточно (я получил результирующий набор html-файлов в каталоге & quot; ... / _ build / html / & quot;). Возможно, Sphinx и Cython эволюционировали с тех пор, как был задан предыдущий вопрос, но у меня не было «подписи» вопросы для решения. Ни одна конкретная директива Cython для использования, ни какое-либо исправление, чтобы применить к Sphinx ...

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

РЕДАКТИРОВАТЬ: Ну, я хотел бы взять мои слова обратно. Я столкнулся с проблемой "Дэн" было упоминание относительно "embedsignature" важно при использовании Epydoc (так что я полагаю, что это проблема и со Sphinx). Активация этой директивы компилятора в любом случае не отправляет совместимые с Python подписи:

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

Надеюсь, что это поможет пользователям Sphinx и 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
Error: User Rate Limit Exceeded
1

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

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
  ...
5

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

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

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

Похожие вопросы