Как получить строки документации из оформленных функций в Python с помощью autodoc? - PullRequest
Новая
       18

Как получить строки документации из оформленных функций в Python с помощью autodoc?

0 голосов
/ 12 февраля 2019

Официально известная проблема с sphinx autodoc заключается в том, что при оформлении вашей функции строка документа не будет отображаться в сгенерированных документах.

На домашней странице autodoc :

Если вы документируете оформленные функции или методы, имейте в виду, что autodoc извлекает свои строки документации, импортируя модуль и проверяя атрибут doc данной функции или метода.Начиная с Python 2.5, functools.wraps () можно использовать для создания хороших функций декорирования.

Итак, использование functools.wraps() работает.

def decorator_func(say_hello_func):       
    """Docstring for decorator_func"""    
    @wraps(say_hello_func)    
    def wrapper_func(hello_var, world_var):    
        """Docstring for wrapper_func"""    
        return say_hello_func(hello_var, world_var)    
    return wrapper_func


@decorator_func    
def say_hello(hello_var, world_var):    
    """Docstring for say_hello function.

    Args:    
        hello_var (str): hello_var    
        world_var (str): world_var

    Returns:    
        str: concatenation of the strings    
    """    
    print hello_var + " " + world_var

производит (с плохим форматированием вставлено) 

say_hello(hello_var, world_var)

Docstring for say_hello function.

Parameters:

·         hello_var (str) – hello_var

·         world_var (str) – world_var

Returns:

concatenation of the strings

Return type:

str

Однако есть случаи, когда у вас есть сторонний пакет, из которого вы можете взять декоратор.Однако нецелесообразно изменять исходный код пакета, добавляя functools.wraps() везде в его исходном коде - работа, которую вы проделали, пропадет после следующего обновления этого пакета, по крайней мере.

Есть ли альтернативное решение, которое не включает изменение исходного кода сторонних пакетов (например, Django), из которого вы берете декораторы?

Простой пример может выглядеть следующим образом.У функции save не будет тянуть строку документации, если вы не перейдете к источнику django и не добавите туда @wraps. 

from django.db import transaction

@transaction.atomic
def save(self):
    """Docstring to be used"""
    pass
...