ドキュメントで型のヒントをスキップする

Aug 21 2020

次の関数について考えてみましょう。

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セクションには、タイプが最初の行にあるものであり、次の行は単なる説明であることが示されています。これらが同じかどうかわからないため、この問題の例を添付しません。もしそうなら、私に知らせてください、そして私は例で更新します。

回答

2 yarnabrina Aug 24 2020 at 19:07

オプションがあるautodoc_typehintsためにsphinx.ext.autodoc。これは、3つのオプションがありますnonedescriptionsignature(デフォルト)。noneまたはのいずれかを使用するとdescription、ヘッダー行の型ヒントが非表示になります。これら2つの間に私が見つけることができる唯一の違いは、docstringに型の提案が含まれていない場合descriptionでも、型のヒントから収集するドキュメントにそれらが表示されることです。

これを使用するには、次の変更が必要ですconf.py

  1. 追加sphinx.ext.autodocextensions(まだ行っていない場合)
  2. セットする autodoc_typehints = "none"
1 mzjn Aug 23 2020 at 00:16

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)