Documentación API de servicio web RESTful con Sphinx

Question

¿Cuál es la mejor manera de marcar métodos/URLs para un servicio web RESTful utilizando ReST/Sphinx? ¿Hay un dominio predeterminado que sea adecuado para marcar las URL con sus posibles parámetros, métodos HTTP, encabezados y contenido del cuerpo?

Algo a lo largo de las líneas de:

.. rest:method:: GET /api/foo 

    :param bar: A valid bar 
    :extension: json or xml 

    Retrieve foos for the given parameters. E.g.:: 

     GET /api/foo.json?bar=baz 

hace algo como esto ya existe o es una de las extensiones predeterminadas utilizables, o voy a tener que escribir uno yo mismo?

Answer 1

El proyecto Sphinx Contrib también parece tener un paquete del dominio HTTP para documentar API RESTful HTTP. Puede encontrar su documentación en el sitio Python packages. No puedo hablar de su estado físico: recién estoy comenzando a investigar Sphinx, y también tengo que documentar las API RESTful, y noté este paquete contribuido.

Answer 2

Dado que no parece haber ninguna solución existente, que han puesto en marcha un dominio HTTP muy simple que puedo usar para marcar métodos de la API:

import re 

from docutils import nodes 

from sphinx import addnodes 
from sphinx.locale import l_, _ 
from sphinx.domains import Domain, ObjType 
from sphinx.directives import ObjectDescription 


http_method_sig_re = re.compile(r'^(GET|POST|PUT|DELETE)?\s?(\S+)(.*)$') 

class HTTPMethod(ObjectDescription): 

    def handle_signature(self, sig, signode): 
     m = http_method_sig_re.match(sig) 
     if m is None: 
      raise ValueError 

     verb, url, query = m.groups() 
     if verb is None: 
      verb = 'GET' 

     signode += addnodes.desc_addname(verb, verb) 
     signode += addnodes.desc_name(url, url) 

     if query: 
      params = query.strip().split() 
      for param in params: 
       signode += addnodes.desc_optional(param, param) 

     return url 


class HTTPDomain(Domain): 
    """HTTP language domain.""" 
    name = 'http' 
    label = 'HTTP' 
    object_types = { 
     'method': ObjType(l_('method'), 'method') 
    } 
    directives = { 
     'method':  HTTPMethod 
    } 

def setup(app): 
    app.add_domain(HTTPDomain) 

Me permite marcar métodos como éste y que van a ser de estilo un tanto visualmente muy bien:

.. http:method:: GET /api/foo/bar/:id/:slug 

    :param id: An id 
    :param slug: A slug 

    Retrieve list of foobars matching given id. 

esta fue mi primera incursión en tanto Esfinge y Python, por lo que este debe ser considerado código muy rudimentaria. ¡Si alguien está interesado en dar cuerpo a esto, por favor, fork this project on Github!