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

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

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

9
converter docstring epydoc python python-sphinx

4 ответов

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

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

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':', lines[i])

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

платежные это инструмент, который может конвертировать Python docstrings и создавать недостающие скелеты. Он может управлять Google, Epydoc (вид javadoc), Numpydoc, reStructuredText (reST, Sphinx по умолчанию) форматы docstring.

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

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

  • установить Pyment

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

$ git clone https://github.com/dadadel/pyment.git
$ cd pyment
$ python setup.py install
  • конвертировать из Epydoc в Сфинкс

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

$ pyment /my/folder/project
6

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

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

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

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

1

как предложил один из комментариев,sphinx-epytext does обеспечивает соответствующую поддержку. Как это работало для меня:

установка очень проста:

pip install -U sphinx-epytext

он содержит один файл process_docstring.py который преобразует epytext markups в reStructuredText markups путем замены @ С .

некоторые из полей, которые я нашел там отсутствующими, были:ivar, var, cvar, vartype

просто расширить существующий список FIELDS in там:

FIELDS.extend(['ivar', 'var', 'cvar', 'vartype'])

Epytext понимает @type для переменных, но сфинкс понимает :vartype.

чтобы исправить это, замените прежние на более поздние внутри process_docstring метод.

большинство синтаксиса или частей docstring, которые Сфинкс не может понять, сообщаются как предупреждения. Вы можете зарегистрировать эти предупреждения, запустив sphinx-build С -w <WarningLogFile>. Согласно моему опыту, Сфинкс очень чувствителен к тому, как поле должно начинаться или заканчиваться, отсутствует форматирование-синтаксис и т. д.

0