Python 3: Sphinx неправильно отображает подсказки типа

#python-sphinx #python-3.5

Вопрос:

Я автоматически создаю HTML-документацию модуля Python 3 из его документации reStructuredText его функций с помощью Sphinx (make HTML). Сгенерированная HTML-документация пока выглядит нормально, но типы параметров сигнатур функций, которые указаны в исходном коде как подсказки типа PEP484, отображаются некорректно.

Например, это пример вывода из сгенерированного Sphinx HTML-документа одной из моих функций:

 static parse_from_file(filename: str) → list
    Parses stuff from a text file.

    Parameters:  filename – the filepath of a textfile to be parsed
    Returns:     list of parsed elements

Я бы ожидал, что это будет выглядеть так:

 static parse_from_file(filename)
    Parses stuff from a text file.

    Parameters:  filename (str) – the filepath of a textfile to be parsed
    Returns:     list of parsed elements
    Return type: list

Вот как на самом деле выглядит код Python:

 def parse_from_file(filename: str) -> list:
    """Parses stuff from a text file.

    :param filename: the filepath of a textfile to be parsed
    :returns: list of parsed elements
    """
    return []

Как я могу заставить Sphinx правильно отображать подсказки типа Python 3?

1. Помещение типов в строку документации не является вариантом? :param str filename: ... и :rtype: list для возвращаемого типа…

2. Это сделало бы его избыточным, и люди в нашем проекте не будут думать об изменении типов два раза. Кроме того, похоже, что Sphinx поддерживает подсказки типа PEP484: github.com/sphinx-doc/sphinx/issues/1968

Ответ №1:

Я решил это самостоятельно, используя расширение sphinx-autodoc-typehints.

Ответ №2:

Существует autodoc_typehints переменная. Начиная с версии 3.0, вы можете установить для 'description' него значение, которое показывает typehints как содержимое функции или метода и удаляет их из подписи.

Так что просто добавьте эту строку в свой conf.py :

 autodoc_typehints = "description"