web-dev-qa-db-ja.com

文書化されたPython関数パラメーターをSphinxマークアップを使用してどのように参照しますか？

以前にドキュメント化された関数パラメーターをPython docstringの別の場所で参照します。次の（確かに完全に人工的な）例を検討してください。

def foo(bar):
    """Perform foo action
    :param bar: The bar parameter
    """

    def nested():
        """Some nested function that depends on enclosing scope's bar parameter.
        I'd like to reference function foo's bar parameter here
        with a link, is that possible?"""
        return bar * bar

    # ...
    return nested()

Sphinxマークアップを使用してパラメーター参照を埋め込む簡単な方法はありますか、またはこれは自動的に行われますか？

（私は完全なSphinx初心者です。私はSphinxのドキュメントをスキャンしてきましたが、この質問に対する回答、または適切なマークアップを示す例が見つかりませんでした。）

pythondocumentationpython-sphinxdocstring
41
Inactivist

このタスクを実行するための拡張機能を作成しました。これまでのところ、スタンドアロンのHTMLビルドと、さらにreadthedocs（いくつかの微調整後）で動作しているようです。

拡張機能は https://pypi.python.org/pypi/sphinx-paramlinks/ で入手できます。

現在、AlembicおよびSQLAlchemyプロジェクト用に展開しています。 （ サンプル ）。

Paramsへのリンクはドキュメントが長すぎることを意味するという提案に同意しません。 Python標準ライブラリはここでは良い例ではありません。stdlib関数は必然的に詳細でシンプルです。1つの関数が複雑な問題の上に乗っている、より粗いタスクを実行するソフトウェア多くの場合、より多くの説明を必要とするパラメータが含まれます。この説明は、他の場所の特定の問題の解決策として非常に貴重なことが多いため、それにリンクできることが非常に重要です。

25
zzzeek

sphinxを使用して関数のパラメーターへの直接参照を取得する簡単な方法はなく、この問題の拡張機能もわかりません。

python domain のドキュメント）では、相互参照できるオブジェクトについて説明しています。

ユーザーに関数barのパラメーターfooへの参照を与えるための可能な方法は、

See parameter ``bar`` in :func:`foo`.

おそらく拡張機能を書くことで直接参照が可能になるでしょう。

30
bmu

sphinx-paramlinksとsphinx.ext.napoleonを併用したい場合は、ここにパッチがあります。 sphinx-paramlinksソースコード（sphinx_paramlinks\sphinx_paramlinks.py、50行目付近）から適切なフラグメントを見つけて、次のコードで置き換えます。

def cvt(m):
    directive, modifier, objname, paramname = (
        m.group(1), m.group(2) or '', name, m.group(3))
    if directive == 'param':
        refname = _refname_from_paramname(paramname, strip_markup=True)
        item = ('single', '%s (%s parameter)' % (refname, objname),
                '%s.params.%s' % (objname, refname), '')
        if LooseVersion(__version__) >= LooseVersion('1.4.0'):
            item += (None,)
        doc_idx.append(item)
    return ":%s %s_sphinx_paramlinks_%s.%s:" % (
        directive, modifier, objname, paramname)
return re.sub(r'^:(param|type) ([^:]+? )?([^:]+?):', cvt, line)

注：正しいインデントについて覚えておいてください。

私はSphinxのスペシャリストではありませんが、これで仕事が完了したようです。

2
Tomasz Kurgan

barのfooの定義に直接リンクする方法を探している場合、ドキュメントが長すぎるか、1つのツリーまたはいくつかの組み合わせのフォレストを無視するよう読者に依頼しています二。

defaultdict Examples から例をとります：

Setting the :attr:`default_factory` to :class:`int` makes the
:class:`defaultdict` useful for counting (like a bag or multiset in other
languages):

もし私が5つの文を collections.defaultdict に読み込むのに煩わされないなら、default_factoryの意味を見つけるために、そこに導かれるに値しないでしょう。

属性参照構文は上記のセクションと同じであることに注意してください。

The first argument provides the initial value for the :attr:`default_factory`
attribute; it defaults to ``None``.

しかし、Sphinxは現在のセクションスコープの外に到達しないため、アンカーとしてではなく、スタイル付きテキストとして後の参照をレンダリングしているようです。これが意図的なものであったとしても、私は驚きません。

0
msw