如何在Sphinx中创建自定义指令

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

这基本上就是文档目前的样子。我希望能够为Sphinx创建一个指令来格式化一个或多个:query_param ...:，就像使用常规:param:一样。

我已经找到了如何制作角色，但它们只能内联工作，而不是数据块。

我应该怎么做才能做到这一点？

Answer 1

可以通过“Sphinx Extensions”使用自定义指令扩展Sphinx。也就是说，您需要实现提供query_param自定义指令的Sphinx扩展，并将此扩展添加到您的Sphinx项目中。

Sphinx文档提供a tutorial实现扩展，实际上它们实现了自定义指令。

参考：

http://www.sphinx-doc.org/en/stable/extensions.html

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