Custom directives in Sphinx

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?

Answers


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


Need Your Help

add xib files to project that has storyboard

iphone ios ipad storyboard xib

I'm iPhone junior, I'm using Xcode 4.3 with iOS5.

Updating a YAML File in Windows

ruby io yaml

I'm trying to update a YAML file with the following code:

About UNIX Resources Network

Original, collect and organize Developers related documents, information and materials, contains jQuery, Html, CSS, MySQL, .NET, ASP.NET, SQL, objective-c, iPhone, Ruby on Rails, C, SQL Server, Ruby, Arrays, Regex, ASP.NET MVC, WPF, XML, Ajax, DataBase, and so on.