Ignorando dicas de tipo na documentação

Question

Vamos considerar a seguinte função:

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

Ao documentar com o Sphinx (v3.2.1), a documentação é gerada da seguinte forma:

No entanto, não vejo sentido em mostrar dicas de tipo como no f(x: int, y:int) -> intcabeçalho da documentação da função e também na Parametersseção. Nesse caso, isso realmente não importa, mas torna muito ilegível com funções com 4-5 argumentos. Existe uma maneira de pular a dica de tipo? Tipo, prefiro que o cabeçalho seja apenas fou f(x, y).

Eu esperava que isso tivesse algo a ver com add_function_parentheses, mas defini-lo como Falsein conf.pynão teve nenhum efeito que eu tenha notado.

Um problema relacionado é que, se a dica de tipo for longa, pode ser como typing.Unionem várias descrições longas, onde eu não quero usar typing.Any, geralmente as escrevo na docstring em várias linhas, aderindo ao limite máximo de linhas. Nesses casos, a Parametersseção mostra que o tipo é o que está na primeira linha, e as próximas linhas são apenas descrições. Não estou anexando um exemplo desse problema, pois não tenho certeza se são iguais ou não. Se estiverem, informe-me e atualizarei com um exemplo.

Answer 1

Existe uma opção autodoc_typehintspara sphinx.ext.autodoc. Isso tem 3 opções: none, descriptione signature(padrão). O uso de noneou descriptionocultará dicas de tipo na linha de cabeçalho. A única diferença que posso encontrar entre esses dois é que, se docstrings não contiverem sugestões de tipo, descriptionainda as mostrará na documentação coletando dicas de tipo.

Para usar isso, as seguintes alterações são necessárias em conf.py:

1. adicionar ( sphinx.ext.autodocse extensionsainda não tiver feito)
2. definirautodoc_typehints = "none"

Answer 2

Um manipulador para o autodoc-process-signatureevento pode alterar assinaturas e retornar anotações de funções e métodos.

Abaixo está um exemplo simples. Se você adicionar esse código a conf.py, todas as assinaturas e anotações de retorno serão removidas da saída.

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