Cómo crear directivas personalizadas en Sphinx

Question

Actualmente estoy documentando una API de descanso escrita en Python. Toda la documentación del proyecto se crea utilizando Sphinx, y para la API REST me gustaría crear algunas directivas especiales. Por ejemplo, digamos que tengo este recurso definido:

@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 

Así es básicamente como se ve la documentación actualmente. Me gustaría poder crear una directiva para Sphinx que formatee uno o más de esos :query_param ...: como lo hace con el :param: normal.

He encontrado cómo hacer papeles, pero solo funcionan en línea, no para bloques de datos.

¿Cómo debo proceder para hacer esto?

Answer 1

Sphinx puede ampliarse con directivas personalizadas a través de "Sphinx Extensions". Es decir, deberá implementar una extensión Sphinx que proporcione la directiva personalizada query_param y agregar esta extensión a su proyecto Sphinx.

La documentación de Sphinx proporciona a tutorial sobre la implementación de extensiones, en las que implementan una directiva personalizada.

Referencia:

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

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