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

Question

Я написал код в 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 из своего кода. Я нашел несколько вариантов и, в частности, смотрел на Сфинкса. Казалось, он сделал то, что я хотел (хотя я изо всех сил пытался заставить его генерировать API, а не руководство для моей программы). Недостаток, однако, в том, что она имеет свой собственный ожидаемый стиль: строки документации

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

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

Answer 1

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

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

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 

Там есть расширение сфинкс (Napoleon), который позволяет Sphinx разобрать этот стиль (или стиль Google, что еще проще).

Answer 2

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

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

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

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

с

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

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