45

以前に文書化された関数パラメーターをPythondocstringの他の場所で参照したいと思います。次の（明らかに完全に人工的な）例を考えてみましょう。

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のドキュメントをスキャンしてきましたが、この質問に対する答えや、適切なマークアップを示す例が見つかりませんでした。）

4

5 に答える 5

35

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

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

barユーザーに関数のパラメーターへの参照を与えるための可能な方法は次のとおりfooです。

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

たぶん、拡張機能を書くことで直接参照が可能になるでしょう。

于 2012-06-24T15:33:27.503 に答える
27

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

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

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

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

于 2013-12-30T18:30:39.207 に答える
2

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)

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

私はスフィンクスのスペシャリストではありませんが、これで仕事は終わりのようです。

于 2018-06-05T14:47:45.527 に答える
0

sphinx-paramlinksが優れたソリューションではないことは言うまでもありませんが、プロジェクトに拡張機能を追加することに少し頑固です。

視覚的なハイライトや、厄介なアンカーアイコンのメリットは得られませんが、そのセクションの前にあるreStructuredTextハイパーリンクターゲットは、少なくともあなたを近づけます。

    def from_existing_id(cls, jobid, **kwargs):
        """Instantiates a new :class:`Job` object from an existing job ID.

        :param jobid: the ID of the previous job
        :param kwargs: keyword arguments supported by :meth:`deserialize`,
            *e.g.*, :ref:`ignore_missing <deserialize_params>`.
        """
        ⋮

    # elsewhere
    def deserialize(self, filename, copy_inputs=False, ignore_missing=False):
        """Reads a disk file into the current :class:`Job` object's config.
    
        .. _deserialize_params:

        :param filename: the filename to read from to disk
        :param copy_inputs: copy input files to output directory
        :param ignore_missing: don't bail if input files are missing
        """
        ⋮

ただし、パラメータリストが長くなるほど、これは役に立たなくなります。

于 2022-02-09T11:49:49.323 に答える
-1

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

defaultdictの例から例をとる：

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は現在のセクションスコープから外れていないように見えるため、後の参照をアンカーではなくスタイル付きテキストとしてレンダリングします。これが意図的なものであったとしても、私は驚かないでしょう。

于 2012-06-23T10:08:50.660 に答える