既存のソリューションがないように見えるため、API メソッドのマークアップに使用できる非常に単純な HTTP ドメインを実装しました。
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)
これにより、このようなメソッドをマークアップすることができ、視覚的にうまくスタイル付けされます。
.. http:method:: GET /api/foo/bar/:id/:slug
:param id: An id
:param slug: A slug
Retrieve list of foobars matching given id.
これは Sphinx と Python の両方への私の最初の進出だったので、これは非常に初歩的なコードと考えるべきです。これを具体化することに興味がある人は、このプロジェクトを Github でフォークしてください。