Автоматический способ переключения с форматирования docstring от epydoc на форматирование dhstnx sphinx?

Question

У меня есть проект, который я документировал с помощью epydoc. Теперь я пытаюсь переключиться на сфинкс. Я отформатировал все свои документы для эпидоков, используя B {}, L {} и т. Д. Для смелости, связывания и т. Д., И используя @param, @return, @raise и т. Д., Чтобы объяснить ввод, вывод, исключения и подобные.

Итак, теперь, когда я переключаюсь на сфинкс, он теряет все эти функции. Есть ли автоматизированный способ конвертировать docstrings, отформатированный для epydocs, в docstrings, отформатированный для sphinx?

Answer 1

Чтобы расширить ответ Kevin Horn, docstrings можно перевести на лету в обработчике событий, вызванном событием autodoc-process-docstring.

Ниже представлена ​​небольшая демонстрация (попробуйте добавить код conf.py). Он заменяет символ @ в некотором общем Epytext fields с :, который используется в соответствующих Sphinx fields.

import re 

re_field = re.compile('@(param|type|rtype|return)') 

def fix_docstring(app, what, name, obj, options, lines): 
    for i in xrange(len(lines)): 
     lines[i] = re_field.sub(r':\1', lines[i]) 

def setup(app): 
    app.connect('autodoc-process-docstring', fix_docstring) 

Answer 2

В теории вы можете написать расширение Sphinx, которое поймало бы любое событие, которое будет запущено при чтении docstring (source_read, может быть?) И перевести docstrings на лету.

Я говорю теоретически, потому что:

1. Я хотел писать такие вещи в течение очень долгого времени, но не удалось обойти его еще.
2. Перевод таких вещей всегда сложнее, чем кажется.

Вы могли бы также, вероятно, попробовать просто заменить все строки документации в ваш код с подобным переводчиком за пределами Сфинкса, возможно, используя ast модуль или что-то подобное.

Answer 3

Pyment является инструментом, который может конвертировать строки документации Python и создать недостающие скелеты. Он может управлять Google, Epydoc (Javadoc стиль), Numpydoc, ReStructuredText (Rest, сфинкс по умолчанию) форматов строку документации.

Принимает один файл или папку (также исследует также подпапки). Для каждого файла он распознает каждый формат docstring и преобразует его в желаемый. В конце будет создан патч для применения к файлу.

Чтобы преобразовать проект:

• установки Pyment

Введите следующую (вы можете использовать virtualenv):

$ git clone https://github.com/dadadel/pyment.git 
$ cd pyment 
$ python setup.py install 

• новообращенный из Epydoc в Сфинкс

Вы можете превратить ваш проект в формате Sphinx (Rest), который является формат вывода по умолчанию, выполнив:

$ pyment /my/folder/project