複合Pythonデータ型のより正確な仕様を提供するためのSphinxの標準またはベストプラクティスはありますか? たとえば、dictマッピングstrを返す関数があり、スタイルstrを使用しています。numpydoc次のようなことをする必要があります:
Returns
-------
out : dict of str to str
またはおそらくdict of str: str？
コンテンツのタイプがわかっているリストの場合、NumPy が次の形式を使用していることに気付きました
foo : list of int
この一般的なユース ケースに従うべき標準またはベスト プラクティスはありますか?
それがベストプラクティスかどうかはわかりませんが、通常は次のようにし:returns: dict( str=str )ます。それがあなたとあなたのプロジェクトにとって最も効果的だと思います。PyCharm のようなものを使用すると、ドキュメント文字列に「最適な」オプションが推奨されますが、別の方法で行うことに気付くと、ゆっくりと推奨が停止されます。PEP8 のようなものはガイドラインのようなものであり (ここでは、パイレーツ オブ カリビアンの印象を最大限に発揮しようとしています)、厳密なルールではありません。一番大事なのは読めるか読めないかです。
インスピレーションの非常に優れたソースの 1 つは、Python 自身のドキュメントです。それを見ていて、見栄えの良いページに気付いた場合は、左側のサイドバーを見て、[ソースを表示] をクリックし、そのスタイルをコピーしてください...私はいつもそうしています :)