Можно ли использовать подсказку типа в python 3 для создания строки документации?

Мы можем указать типы параметров функции, используя docstring в python:

def f1(a):
    """
    :param a: an input.
    :type a: int
    :return: the input integer.
    :rtype: int
    """
    return a

Для f1 autodoc генерирует следующий документ:

fun1(a)
    Parameters : a (int) – an input.
    Returns    : the input integer.
    Return type: int

В python 3 типы также могут быть указаны подсказкой типа:

def f2(a: int):
    """
    :param a: an input.
    :return: the input integer.
    :rtype: int
    """
    return a

Когда мы запускаем autodoc, он ставит тип по объявлению параметра, а не по описанию:

f2(a: int)
    Parameters : a – an input.
    Returns    : the input integer.
    Return type: int

Можно ли сгенерировать документацию как f1, используя аннотацию вместо строки документации? Я использую питон 3.6. Благодарю вас!


person Jinho Choi    schedule 16.02.2017    source источник
comment
Очевидно, вы можете написать код, который будет делать то, что вы хотите.   -  person John Coleman    schedule 16.02.2017
comment
См. это: github.com/sphinx-doc/sphinx/issues/1968 Вероятно, с этим изменением вы сможете получить поддержку аннотаций типов из коробки.   -  person user3159253    schedule 16.02.2017
comment
Да, надеюсь, скоро он будет поддерживаться Sphinx.   -  person Jinho Choi    schedule 17.02.2017


Ответы (1)


Пока нет, насколько мне известно, Sphinx еще не поддерживает это. Ошибка, упомянутая в комментарии, касалась представления подсказок типа, а не их позиционирования.

Я знаю, что в настоящее время существует расширение для Sphinx, которое позаботится об этом за вас, оно называется sphinx-autodoc. -подсказки. Вы, вероятно, могли бы использовать это на данный момент.

person Dimitris Fasarakis Hilliard    schedule 16.02.2017
comment
Замечательно, пока что я буду использовать этот плагин. Надеемся, что эта функция будет встроена в Sphinx. Спасибо. - person Jinho Choi; 17.02.2017
comment
Если кто-то также хочет использовать Napoleon, этот ответ содержит более подробную информацию о том, как заставить их хорошо играть вместе. - person ssokolow; 29.12.2019