如何在獅身人面像中創建自定義指令

Question

我目前正在記錄用Python編寫的其餘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 

這基本上是文檔目前的樣子。我希望能夠爲Sphinx創建一個指令，這些指令格式化一個或多個:query_param ...:，就像它與常規的:param:一樣。

我發現瞭如何製作角色，但它們只能在內聯中使用，而不能用於數據塊。

如何我該怎麼做？

Answer 1

獅身人面像可以通過自定義指令通過「Sphinx Extensions」進行擴展。也就是說，您需要實現一個提供query_param自定義指令的Sphinx擴展，並將此擴展添加到您的Sphinx項目中。

Sphinx文檔提供a tutorial實現擴展，其中他們確實實現了自定義指令。

參考：

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

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