python - 如何在 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: 所做的那样。

我找到了创建角色的方法，但它们只能内联工作，不能用于数据 block 。

我应该如何做这个？

Answer 1

Sphinx 可以通过“Sphinx Extensions”使用自定义指令进行扩展。也就是说，您需要实现一个提供 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