如何在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文档提供了有关实现扩展的教程,其中确实实现了自定义指令.

参考:

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

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