Создание API из строк документации Python, написанных в PEP8

Я написал код на Python. Я старался следовать общепринятым правилам написания полезных комментариев в начале функций. Мой стиль - PEP8, например.

def __init__(self, f_name=None, list_=None, cut_list=None, n_events=None, description=None):
        """
        Parse an LHCO or ROOT file into a list of Event objects.

        It is possible to initialize an Events class without a LHCO file,
        and later append events to the list.

        Arguments:
        f_name -- Name of an LHCO or ROOT file, including path
        list_ -- A list for initalizing Events
        cut_list -- Cuts applied to events and their acceptance
        n_events -- Number of events to read from LHCO file
        description -- Information about events
        """

Я хочу автоматически генерировать полезный API из своего кода. Я нашел несколько вариантов и смотрел, в частности, на Sphinx. Казалось, он делает то, что я хотел (хотя я изо всех сил пытался заставить его генерировать API, а не руководство для моей программы). Недостатком, однако, было то, что у него есть собственный ожидаемый стиль для строк документации:

"""
:param x: My parameter
:type x: Its type
"""

Действительно ли мне лучше переписать все мои строки документации с этим синтаксисом? Они создают хороший API, но мне не нравятся их в коде, и это займет много времени, если это окажется плохой идеей. Что такое стандарт, лучшая практика? Должен ли я конвертировать? Если да, может ли что-то сделать это автоматически для меня?


python python-sphinx docstring
person innisfree    schedule 15.10.2015    source источник

Ответы (2)


arrow_upward
1
arrow_downward

Формат Sphinx по умолчанию для строк документации действительно очень мощный и определенно стоит потраченного времени, если вы хотите создать чистую документацию по API и если вам нужно пересматривать собственный код через месяцы, годы. Так что да, это хорошая идея.

Если вам не нравится синтаксис Sphinx-ReST по умолчанию, вы можете попробовать написать свои строки документации как это делает Numpy, например:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    """
    return True

Существует расширение Sphinx (Napoleon), позволяющее Sphinx анализировать этот стиль (или стиль, который еще проще).

person Leo    schedule 15.10.2015

arrow_upward
1
arrow_downward

Я думаю, что синтаксис Sphinx довольно легкий (радуйтесь, что это не Javadoc), поэтому с точки зрения довольно сырого кода это не является серьезным недостатком.

Моя IDE, PyCharm, автоматически создает скелеты в стиле Sphinx, когда я добавляю строку документации к функции. Итак, есть некоторые разработчики, которые кое-что знают о Python (и которым также нравится продвигать стиль PEP8 в других областях) и рекомендуют Sphinx. PyCharm даже имеет систему подсказок типов, используемую для вывода и проверки типов, которая начинается с проверки объявлений в строке документации.

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

^(\s+)(\w+) -- (.+)$

с

$1:param $2: $3\n$1:type $2:

где $n представляет n-ю группу. Конечно, вам нужно будет заполнить тип самостоятельно.

person Alex Hall    schedule 15.10.2015