Come creare direttive personalizzate in Sfinge

Question

Attualmente sto documentando un'API di riposo scritta in Python. Tutta la documentazione del progetto viene creata utilizzando Sphinx e per l'API REST vorrei creare alcune direttive speciali. Ad esempio, supponiamo di avere questa risorsa definita:

@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 

Questo è fondamentalmente come appare la documentazione attualmente. Mi piacerebbe essere in grado di creare una direttiva per Sphinx che formatta uno o più di quelli :query_param ...: proprio come fa con il normale :param:.

Ho trovato come creare ruoli, ma funzionano solo in linea, non per blocchi di dati.

Come devo fare questo?

Answer 1

La Sfinge può essere estesa con le direttive personalizzate tramite "Sphinx Extensions". Cioè, dovrai implementare un'estensione Sfinge che fornisca la direttiva personalizzata query_param e aggiungere questa estensione al tuo progetto Sphinx.

La documentazione di Sphinx fornisce a tutorial sulle estensioni di implementazione, in cui implementano effettivamente una direttiva personalizzata.

Riferimento:

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

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