So erstellen Sie benutzerdefinierte Anweisungen in Sphinx

Question

Ich dokumentiere derzeit eine Rest-API in Python geschrieben. Die gesamte Projektdokumentation wird mit Sphinx erstellt, und für die REST-API möchte ich einige spezielle Anweisungen erstellen. Nehmen wir zum Beispiel an, ich habe diese Ressource definiert:

@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 

Das ist im Grunde, wie die Dokumentation derzeit aussieht. Ich würde gerne in der Lage sein, eine Direktive für Sphinx zu erstellen, die eines oder mehrere dieser :query_param ...: genauso formatiert wie es mit regulären :param:.

Ich habe gefunden, wie man Rollen macht, aber sie arbeiten nur inline, nicht für Datenblöcke.

Wie sollte ich darüber gehen, dies zu machen?

Answer 1

Sphinx kann mit benutzerdefinierten Anweisungen über "Sphinx Extensions" erweitert werden. Das heißt, Sie müssen eine Sphinx-Erweiterung mit der benutzerdefinierten Richtlinie query_param implementieren und diese Erweiterung zu Ihrem Sphinx-Projekt hinzufügen.

Sphinx-Dokumentation bietet a tutorial bei der Implementierung von Erweiterungen, in denen sie tatsächlich eine benutzerdefinierte Richtlinie implementieren.

Referenz:

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

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