スフィンクスでカスタムディレクティブを作成するには

Question

私は現在、Pythonで書かれたrest APIを文書化しています。すべてのプロジェクトのドキュメントはSphinxを使用して作成され、REST APIのためにいくつかの特別なディレクティブを作成したいと考えています。たとえば、このリソースが定義されているとしましょう：

@resource("/user/<email>", method="GET") 
def user_details (email): 
    """ Returns detailed information about a user account. 

    :resource GET: /user/<email> 
    :query_param a_param: Some kind of query param. 
    """ 
    # Do stuff and return user details 

これは基本的にドキュメントの外観です。私は、スフィンクスの指示文を作成して、:query_param ...:のうちの1つ以上を通常の:param:のようにフォーマットすることができるようにしたいと考えています。

ロールの作成方法はわかりましたが、データのブロックではなく、インラインでしか動作しません。

どうすればいいですか？

Answer 1

スフィンクスは "Sphinx Extensions"経由でカスタムディレクティブで拡張できます。つまり、query_paramカスタムディレクティブを提供するSphinx拡張を実装し、この拡張をSphinxプロジェクトに追加する必要があります。

スフィンクスのドキュメントでは、実際にカスタムディレクティブを実装する拡張機能の実装についてa tutorialを提供しています。

参考：

http://sphinx.pocoo.org/extensions.html

http://sphinx-doc.org/extdev/index.html#dev-extensions