如何在 Sphinx 中创建自定义指令 [英] How to create custom directives in Sphinx

问题描述

我目前正在记录一个用 Python 编写的 rest API.所有项目的文档都是使用 Sphinx 创建的，对于 REST API，我想创建一些特殊的指令.例如，假设我定义了此资源:

I'm currently documenting a rest API written in Python. All the project's documentation is created using Sphinx, and for the REST API I would like to create some special directives. For instance, let's say I have this resource defined:

@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: 所做的一样.

That's basically how the documentation currently looks. I would like to be able to create a directive for Sphinx that formats one or more of those :query_param ...: just like it does with regular :param:.

我已经找到了如何创建角色，但它们只能内联工作，不能用于数据块.

I have found how to make roles, but they only work inline, not for blocks of data.

我应该如何做这个?

推荐答案

Sphinx 可以通过 "Sphinx 扩展".也就是说，您需要实现一个提供 query_param 自定义指令的 Sphinx 扩展，并将此扩展添加到您的 Sphinx 项目中.

Sphinx can be extended with custom directives via "Sphinx Extensions". That is, you will need to implement a Sphinx extension providing the query_param custom directive, and add this extension to your Sphinx project.

Sphinx 文档提供了教程关于实现扩展，它们确实实现了自定义指令.

Sphinx documentation provides a tutorial on implementing extensions, in which they implement a custom directive indeed.

参考:

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

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

这篇关于如何在 Sphinx 中创建自定义指令的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！