Sphinxでは、モジュール内にあるが、クラスとメソッドの外にあるドキュメントストリング/コメントを含める方法

Question

私のパッケージにはutilsモジュールがあります。インスタンス化を必要としないスタンドアロンのいくつかのメソッドで構成されています。

私のような、このutilsファイル内のいくつかの一般的なコメント/ドキュメンテーション文字列を配置したいと思います：上記からわかるように

import os 
import json 

""" 
Miscellaneous methods that help in <<blah blah>> 
Does not require explicit instantiation. 

The following actions can be performed: 
=============== =============== 
Action   Method 
=============== =============== 
Get a    :meth:`methoda` 
Get b    :meth:`methodb` 
""" 

def methoda(data): 
    "Gets A ..." 
    ... 

def methodb(data): 
    "Gets B ..." 
    ... 

、ドキュメンテーション文字列は、個々のメソッドへのリンクを含むテーブルを持っています。現在、私のindex.rstはutils含めるには、この部分があります：現在

Utilities 
============ 
.. automodule:: packagename.utils 
    :members: 

を、私は任意のクラスの外で（適切にドキュメントに表示された個々のメソッドのドキュメンテーション文字列ではなく、モジュールの最上位レベルのドキュメンテーション文字列を取得したり、方法）。スフィンクスを持っている最善の方法は何ですか？

トップレベルのドキュメントストリングをindex.rstなどのようにこのファイルの外に移動することが1つの選択肢になる可能性がありますが、これを行わずにソースファイル内に保持することをお勧めします。

Answer 1

彼のコメントのためにjonsharpeに感謝し、これを行う適切な方法に私を導く。

""" 
Miscellaneous methods that help in <<blah blah>> 
Does not require explicit instantiation. 

The following actions can be performed: 
=============== =============== 
Action   Method 
=============== =============== 
Get a    :meth:`methoda` 
Get b    :meth:`methodb` 
""" 

import os 
import json 

def methoda(data): 
    "Gets A ..." 
    ... 

def methodb(data): 
    "Gets B ..." 
    ... 

そして、それはそれだ：他人による将来の参考のために

は、私は基本的にファイルの先頭にドキュメンテーション文字列を移動しました！すべてが機能します。