Пропуск подсказок по типу в документации

Question

Рассмотрим следующую функцию:

def f(x: int, y: int) -> int:
    """Get sum of two integers.

    Parameters
    ----------
    x : int
        first integer
    y : int
        second integer

    Returns
    -------
    int
        sum of the provided integers
    """
    return x + y

При документировании с помощью Sphinx (v3.2.1) документация создается в следующем виде:

Однако я не вижу смысла показывать подсказки типа, как в f(x: int, y:int) -> int в заголовке документации функции, а также в Parametersраздел. В данном случае это не имеет особого значения, но делает его очень нечитаемым с функциями с 4-5 аргументами. Есть ли способ пропустить подсказку типа? Я предпочитаю, чтобы заголовок был простоf или f(x, y).

Я ожидал, что это как-то связано с add_function_parentheses, но установив его как False в conf.py я не заметил никакого эффекта.

Связанная проблема заключается в том, что если подсказка типа длинная, это может быть похоже на typing.Union с несколькими длинными описаниями, где я не хочу использовать typing.Any, я часто пишу их в строке документации на нескольких строках, придерживаясь максимального количества строк. В этих случаяхParametersРаздел показывает, что тип - это то, что находится в первой строке, а следующие строки - просто описания. Я не прилагаю примера этой проблемы, так как не уверен, одинаковы они или нет. Если да, дайте мне знать, и я приведу пример.

Answer 1

Есть вариант autodoc_typehints за sphinx.ext.autodoc. У этого есть 3 варианта:none, description а также signature(дефолт). Использование любого изnone или descriptionскроет подсказки типа в строке заголовка. Единственное различие, которое я могу найти между этими двумя, заключается в том, что если строки документации не содержат предложений типа,description по-прежнему будет показывать их в документации, собираемой из подсказок типов.

Чтобы использовать это, в conf.py:

1. добавлять sphinx.ext.autodoc в extensions (если еще не сделано)
2. установлен autodoc_typehints = "none"

Answer 2

Обработчик для autodoc-process-signature может изменять подписи и возвращать аннотации функций и методов.

Ниже приведен простой пример. Если вы добавите этот код в conf.py, все подписи и аннотации возврата будут удалены из вывода.

def fix_sig(app, what, name, obj, options, signature, return_annotation):
    return ("", "")
 
def setup(app):
    app.connect("autodoc-process-signature", fix_sig)