在狮身人面像中的自定义指令 [英] Custom directives in Sphinx

问题描述

我正在记录一个用Python编写的休息API。所有项目的文档都是使用Sphinx创建的，对于REST API，我想创建一些特殊的指令。例如，假设我有这个资源定义：

  @resource（/ user /< email>，method = GET）
 def user_details（email）：
返回有关用户帐户的详细信息
 
：资源GET：/ user /< email> 
：query_param a_param：某种查询参数

＃填写并返回用户详细信息
  

这基本上是文档当前的外观，我想要为Sphinx创建一个格式化一个或多个的指令：query_param ...： code>就像常规一样：param：。

我尝试搜索google，但是只有我能找到的是如何发挥作用，但它们只能在线工作，而不是用于数据块。

我应该如何去这样做？

解决方案

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

Sphinx文档提供了有关实施扩展的教程，其中他们实现了一个自定义的指令。

参考：

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

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

I'm currently documenting a rest API written in Python. All the project's documentation is created using Sphinx, for the REST API I would like to create some special directvies. 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

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 tried searching google, but the only thing I can find is how to make roles, but they only work inline, not for blocks of data.

How should I go about making this?

解决方案

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 documentation provides a tutorial on implementing extensions, in which they implement a custom directive indeed.

Reference:

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

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

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