Блог

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

 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 , я часто записываю их в docstring в нескольких строках, придерживаясь максимального ограничения строки. В таких случаях Parameters раздел показывает, что тип — это то, что находится в первой строке, а следующие строки — это просто описания. Я не прилагаю пример этой проблемы, поскольку я не уверен, совпадают ли они или нет. Если они есть, пожалуйста, дайте мне знать, и я обновлю их примером.

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

Чтобы использовать это, требуются следующие изменения в conf.py :

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

Обработчик для 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)