Автоматизированный способ перехода от форматирования строки документации epydoc к форматированию строки sphinx?

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

Так что теперь, когда я переключаюсь на сфинкса, он теряет все эти функции. Существует ли автоматический способ преобразования строк документов, отформатированных для эпидок, в строки документов, отформатированных для сфинкса?

Источник

4 ответа

Решение

Чтобы расширить ответ Кевина Хорна, строки документации могут быть преобразованы на лету в обработчике событий, вызванном событием 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':\1', lines[i])

def setup(app):
    app.connect('autodoc-process-docstring', fix_docstring)
Источник

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

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

Чтобы конвертировать ваш проект:

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

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

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

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

$ pyment /my/folder/project
Источник

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

Установить его очень просто:

pip install -U sphinx-epytext

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

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

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

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

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

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

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

Источник

Теоретически вы можете написать расширение Sphinx, которое будет перехватывать любое событие, которое запускается при чтении строки документа (source_read, может быть?) и переведите строки документов на лету.

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

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

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

Источник
Другие вопросы по тегам