gnunet-handbook

The GNUnet Handbook
Log | Files | Refs

__init__.py (29310B)


      1 """
      2     sphinxcontrib.httpdomain
      3     ~~~~~~~~~~~~~~~~~~~~~~~~
      4 
      5     Domains for documenting HTTP APIs and WebSocket connections.
      6 
      7     :copyright: Copyright 2011 by Hong Minhee
      8     :license: BSD, see LICENSE for details.
      9 
     10 """
     11 
     12 import re
     13 import os
     14 
     15 from docutils import nodes
     16 
     17 from pygments.lexer import RegexLexer, bygroups
     18 from pygments.lexers import get_lexer_by_name
     19 from pygments.token import Literal, Text, Operator, Keyword, Name, Number
     20 from pygments.util import ClassNotFound
     21 
     22 from sphinx import addnodes
     23 from sphinx.roles import XRefRole
     24 from sphinx.domains import Domain, ObjType, Index
     25 from sphinx.directives import ObjectDescription, directives
     26 from sphinx.util import logging
     27 from sphinx.util.nodes import make_refnode
     28 from sphinx.util.docfields import GroupedField, TypedField
     29 from sphinx.util.docutils import Reporter, LoggingReporter
     30 from sphinx.locale import get_translation
     31 from ._path_signature import render_path_signature
     32 from .websocket import WebSocketDomain
     33 _ = get_translation('httpdomain')
     34 
     35 logger = logging.getLogger(__name__)
     36 
     37 
     38 class DummyDocument(object):
     39     """Used where the signature requires a docutils.node.Document but only its reporter
     40     is being used.
     41 
     42     Up until the current Sphinx 2.3.1 calls to env.get_doctree() (which would get
     43     us said docutils.node.Document) result in pickle.load() calls which are expensive
     44     enough to dominate the runtime entirely when the number of endpoints and references
     45     is large enough.
     46     """
     47 
     48     def __init__(self, reporter):
     49         self.reporter = reporter
     50 
     51 
     52 class DocRef(object):
     53     """Represents a reference to an abstract specification."""
     54 
     55     def __init__(self, base_url, anchor, section):
     56         self.base_url = base_url
     57         self.anchor = anchor
     58         self.section = section
     59 
     60     def __repr__(self):
     61         """Returns the URL onto related specification section for the related
     62         object."""
     63         return '{0}#{1}{2}'.format(self.base_url, self.anchor, self.section)
     64 
     65 
     66 class RFC2616Ref(DocRef):
     67     """Represents a reference to RFC2616.
     68     In 2014, RFC2616 was replaced by multiple RFCs (7230-7237)."""
     69 
     70     def __init__(self, section):
     71         url = 'https://www.w3.org/Protocols/rfc2616/rfc2616-sec{0:d}.html'
     72         url = url.format(int(section))
     73         super(RFC2616Ref, self).__init__(url, 'sec', section)
     74 
     75 
     76 class IETFRef(DocRef):
     77     """Represents a reference to the specific IETF RFC."""
     78 
     79     def __init__(self, rfc, section):
     80         url = 'https://www.rfc-editor.org/info/rfc{0:d}'.format(rfc)
     81         super(IETFRef, self).__init__(url, 'section-', section)
     82 
     83 
     84 class EventSourceRef(DocRef):
     85 
     86     def __init__(self, section):
     87         url = 'https://html.spec.whatwg.org/multipage/server-sent-events.html'
     88         super(EventSourceRef, self).__init__(url, section, '')
     89 
     90 
     91 class CORSRef(DocRef):
     92     """Represents a reference to W3 Cross-Origin Resource Sharing recommendation."""
     93 
     94     def __init__(self, name, type):
     95         url = 'https://www.w3.org/TR/cors/'
     96         super(CORSRef, self).__init__(url, name, '-' + type)
     97 
     98 
     99 #: Mapping from lowercase HTTP method name to :class:`DocRef` object which
    100 #: maintains the URL which points to the section of the RFC which defines that
    101 #: HTTP method.
    102 METHOD_REFS = {
    103     'patch': IETFRef(5789, 2),
    104     'options': IETFRef(7231, '4.3.7'),
    105     'get': IETFRef(7231, '4.3.1'),
    106     'head': IETFRef(7231, '4.3.2'),
    107     'post': IETFRef(7231, '4.3.3'),
    108     'put': IETFRef(7231, '4.3.4'),
    109     'delete': IETFRef(7231, '4.3.5'),
    110     'trace': IETFRef(7231, '4.3.8'),
    111     'connect': IETFRef(7231, '4.3.6'),
    112     'copy': IETFRef(2518, 8.8),
    113     'query': IETFRef(10008, 2),
    114     'any': ''
    115 }
    116 
    117 
    118 #: Mapping from HTTP header name to :class:`DocRef` object which
    119 #: maintains the URL which points to the related section of the RFC.
    120 HEADER_REFS = {
    121     'Accept': IETFRef(7231, '5.3.2'),
    122     'Accept-Charset': IETFRef(7231, '5.3.3'),
    123     'Accept-Encoding': IETFRef(7231, '5.3.4'),
    124     'Accept-Language': IETFRef(7231, '5.3.5'),
    125     'Accept-Query': IETFRef(10008, 3),
    126     'Accept-Ranges': IETFRef(7233, 2.3),
    127     'Age': IETFRef(7234, 5.1),
    128     'Allow': IETFRef(7231, '7.4.1'),
    129     'Authorization': IETFRef(7235, 4.2),
    130     'Cache-Control': IETFRef(7234, 5.2),
    131     'Connection': IETFRef(7230, 6.1),
    132     'Content-Encoding': IETFRef(7231, '3.1.2.2'),
    133     'Content-Language': IETFRef(7231, '3.1.3.2'),
    134     'Content-Length': IETFRef(7230, '3.3.2'),
    135     'Content-Location': IETFRef(7231, '3.1.4.2'),
    136     'Content-MD5': RFC2616Ref(14.15), # removed
    137     'Content-Range': IETFRef(7233, 4.2),
    138     'Content-Type': IETFRef(7231, '3.1.1.5'),
    139     'Cookie': IETFRef(2109, '4.3.4'), # also RFC6265 section 5.4
    140     'Date': IETFRef(7231, '7.1.1.2'),
    141     'Destination': IETFRef(2518, 9.3),
    142     'ETag': IETFRef(7232, 2.3),
    143     'Expect': IETFRef(7231, '5.1.1'),
    144     'Expires': IETFRef(7234, 5.3),
    145     'From': IETFRef(7231, '5.5.2'),
    146     'Host': IETFRef(7230, 5.4),
    147     'If-Match': IETFRef(7232, 3.1),
    148     'If-Modified-Since': IETFRef(7232, 3.3),
    149     'If-None-Match': IETFRef(7232, 3.2),
    150     'If-Range': IETFRef(7233, 3.2),
    151     'If-Unmodified-Since': IETFRef(7232, 3.4),
    152     'Last-Event-ID': EventSourceRef('last-event-id'),
    153     'Last-Modified': IETFRef(7232, 2.2),
    154     'Link': IETFRef(5988, '5'),
    155     'Location': IETFRef(7231, '7.1.2'),
    156     'Max-Forwards': IETFRef(7231, '5.1.2'),
    157     'Pragma': IETFRef(7234, 5.4),
    158     'Proxy-Authenticate': IETFRef(7235, 4.3),
    159     'Proxy-Authorization': IETFRef(7235, 4.4),
    160     'Range': IETFRef(7233, 3.1),
    161     'Referer': IETFRef(7231, '5.5.2'),
    162     'Retry-After': IETFRef(7231, '7.1.3'),
    163     'Server': IETFRef(7231, '7.4.2'),
    164     'Set-Cookie': IETFRef(2109, '4.2.2'),
    165     'TE': IETFRef(7230, 4.3),
    166     'Trailer': IETFRef(7230, 4.4),
    167     'Transfer-Encoding': IETFRef(7230, '3.3.1'),
    168     'Upgrade': IETFRef(7230, 6.7),
    169     'User-Agent': IETFRef(7231, '5.5.3'),
    170     'Vary': IETFRef(7231, '7.1.4'),
    171     'Via': IETFRef(7230, '5.7.1'),
    172     'Warning': IETFRef(7234, 5.5),
    173     'WWW-Authenticate': IETFRef(7235, 4.1),
    174     'Access-Control-Allow-Origin': CORSRef('access-control-allow-origin',
    175                                            'response-header'),
    176     'Access-Control-Allow-Credentials': CORSRef('access-control-allow-credentials',
    177                                                 'response-header'),
    178     'Access-Control-Expose-Headers': CORSRef('access-control-expose-headers',
    179                                              'response-header'),
    180     'Access-Control-Max-Age': CORSRef('access-control-max-age',
    181                                       'response-header'),
    182     'Access-Control-Allow-Methods': CORSRef('access-control-allow-methods',
    183                                             'response-header'),
    184     'Access-Control-Allow-Headers': CORSRef('access-control-allow-headers',
    185                                             'response-header'),
    186     'Origin': CORSRef('origin', 'request-header'),
    187     'Access-Control-Request-Method': CORSRef('access-control-request-method',
    188                                              'response-header'),
    189     'Access-Control-Request-Headers': CORSRef('access-control-request-headers',
    190                                               'response-header'),
    191 }
    192 
    193 
    194 HTTP_STATUS_CODES = {
    195     100: 'Continue',
    196     101: 'Switching Protocols',
    197     102: 'Processing',
    198     200: 'OK',
    199     201: 'Created',
    200     202: 'Accepted',
    201     203: 'Non Authoritative Information',
    202     204: 'No Content',
    203     205: 'Reset Content',
    204     206: 'Partial Content',
    205     207: 'Multi Status',
    206     226: 'IM Used',              # see RFC 3229
    207     300: 'Multiple Choices',
    208     301: 'Moved Permanently',
    209     302: 'Found',
    210     303: 'See Other',
    211     304: 'Not Modified',
    212     305: 'Use Proxy',
    213     307: 'Temporary Redirect',
    214     308: 'Permanent Redirect',
    215     400: 'Bad Request',
    216     401: 'Unauthorized',
    217     402: 'Payment Required',     # unused
    218     403: 'Forbidden',
    219     404: 'Not Found',
    220     405: 'Method Not Allowed',
    221     406: 'Not Acceptable',
    222     407: 'Proxy Authentication Required',
    223     408: 'Request Timeout',
    224     409: 'Conflict',
    225     410: 'Gone',
    226     411: 'Length Required',
    227     412: 'Precondition Failed',
    228     413: 'Request Entity Too Large',
    229     414: 'URI Too Long',
    230     415: 'Unsupported Media Type',
    231     416: 'Requested Range Not Satisfiable',
    232     417: 'Expectation Failed',
    233     418: "I'm a teapot",        # see RFC 2324
    234     422: 'Unprocessable Entity',
    235     423: 'Locked',
    236     424: 'Failed Dependency',
    237     425: 'Too Early',           # RFC 8470
    238     426: 'Upgrade Required',
    239     429: 'Too Many Requests',
    240     449: 'Retry With',           # proprietary MS extension
    241     451: 'Unavailable For Legal Reasons',
    242     500: 'Internal Server Error',
    243     501: 'Not Implemented',
    244     502: 'Bad Gateway',
    245     503: 'Service Unavailable',
    246     504: 'Gateway Timeout',
    247     505: 'HTTP Version Not Supported',
    248     507: 'Insufficient Storage',
    249     510: 'Not Extended'
    250 }
    251 
    252 WEBDAV_STATUS_CODES = [207, 422, 423, 424, 507]
    253 
    254 def sort_by_method(entries):
    255     def cmp(item):
    256         order = ['HEAD', 'GET', 'POST', 'PUT', 'DELETE', 'PATCH',
    257                  'OPTIONS', 'TRACE', 'CONNECT', 'COPY', 'ANY']
    258         method = item[0].split(' ', 1)[0]
    259         if method in order:
    260             return order.index(method)
    261         return 100
    262     return sorted(entries, key=cmp)
    263 
    264 
    265 def http_resource_anchor(method, path):
    266     path = re.sub(r'[{}]', '', re.sub(r'[<>:/]', '-', path))
    267     return method.lower() + '-' + path
    268 
    269 
    270 class HTTPResource(ObjectDescription):
    271 
    272     doc_field_types = [
    273         TypedField('parameter', label=_('Parameters'),
    274                    names=('param', 'parameter', 'arg', 'argument'),
    275                    typenames=('paramtype', 'type')),
    276         TypedField('jsonparameter', label=_('JSON Parameters'),
    277                    names=('jsonparameter', 'jsonparam', 'json'),
    278                    typenames=('jsonparamtype', 'jsontype')),
    279         TypedField('requestjsonobject', label=_('Request JSON Object'),
    280                    names=('reqjsonobj', 'reqjson', '>jsonobj', '>json'),
    281                    typenames=('reqjsonobj', '>jsonobj')),
    282         TypedField('requestjsonarray', label=_('Request JSON Array of Objects'),
    283                    names=('reqjsonarr', '>jsonarr'),
    284                    typenames=('reqjsonarrtype', '>jsonarrtype')),
    285         TypedField('responsejsonobject', label=_('Response JSON Object'),
    286                    names=('resjsonobj', 'resjson', '<jsonobj', '<json'),
    287                    typenames=('resjsonobj', '<jsonobj')),
    288         TypedField('responsejsonarray', label=_('Response JSON Array of Objects'),
    289                    names=('resjsonarr', '<jsonarr'),
    290                    typenames=('resjsonarrtype', '<jsonarrtype')),
    291         TypedField('queryparameter', label=_('Query Parameters'),
    292                    names=('queryparameter', 'queryparam', 'qparam', 'query'),
    293                    typenames=('queryparamtype', 'querytype', 'qtype')),
    294         GroupedField('formparameter', label=_('Form Parameters'),
    295                      names=('formparameter', 'formparam', 'fparam', 'form')),
    296         GroupedField('requestheader', label=_('Request Headers'),
    297                      rolename='header',
    298                      names=('>header', 'reqheader', 'requestheader')),
    299         GroupedField('responseheader', label=_('Response Headers'),
    300                      rolename='header',
    301                      names=('<header', 'resheader', 'responseheader')),
    302         GroupedField('statuscode', label=_('Status Codes'),
    303                      rolename='statuscode',
    304                      names=('statuscode', 'status', 'code'))
    305     ]
    306 
    307     option_spec = {
    308         'deprecated': directives.flag,
    309         'noindex': directives.flag,
    310         'addtoc': directives.flag,
    311         'synopsis': lambda x: x,
    312     }
    313 
    314     method = NotImplemented
    315     noindex = False
    316 
    317     def run(self):
    318         # ObjectDescription.run() skips add_target_and_index() entirely when
    319         # the noindex option is set, which would drop the per-page anchor
    320         # along with the global registration. Anchors are per-document ids
    321         # and cannot collide across pages, so pop the option before running
    322         # the base class and gate only the registration in
    323         # add_target_and_index().
    324         self.noindex = 'noindex' in self.options
    325         self.options.pop('noindex', None)
    326         nodes = super().run()
    327         if self.noindex:
    328             for node in nodes:
    329                 if isinstance(node, addnodes.desc):
    330                     node['noindex'] = node['no-index'] = True
    331         return nodes
    332 
    333     def handle_signature(self, sig, signode):
    334         method = self.method.upper() + ' '
    335         signode += addnodes.desc_name(method, method)
    336         path = render_path_signature(sig, signode)
    337         fullname = self.method.upper() + ' ' + path
    338         signode['method'] = self.method
    339         signode['path'] = sig
    340         signode['fullname'] = fullname
    341         return (fullname, self.method, sig)
    342 
    343     def needs_arglist(self):
    344         return False
    345 
    346     def add_target_and_index(self, name_cls, sig, signode):
    347         signode['ids'].append(http_resource_anchor(*name_cls[1:]))
    348         if not self.noindex:
    349             self.env.domaindata['http'][self.method][sig] = (
    350                 self.env.docname,
    351                 self.options.get('synopsis', ''),
    352                 'deprecated' in self.options)
    353 
    354     def get_index_text(self, modname, name):
    355         return ''
    356 
    357     def _object_hierarchy_parts(self, sig_node):
    358         if 'addtoc' in self.options:
    359             if 'fullname' not in sig_node:
    360                 return ()
    361             path = sig_node.get('path')
    362             method = sig_node.get('method')
    363             if not path or not sig_node:
    364                 return ()
    365             return tuple(path.split('/')) + (method, sig_node['fullname'])
    366         return ()
    367 
    368     def _toc_entry_name(self, sig_node):
    369         if 'addtoc' in self.options:
    370             if not sig_node.get('_toc_parts'):
    371                 return ''
    372 
    373             return sig_node['_toc_parts'][-1]
    374         return ''
    375 
    376 
    377 class HTTPOptions(HTTPResource):
    378 
    379     method = 'options'
    380 
    381 
    382 class HTTPHead(HTTPResource):
    383 
    384     method = 'head'
    385 
    386 
    387 class HTTPPatch(HTTPResource):
    388 
    389     method = 'patch'
    390 
    391 
    392 class HTTPPost(HTTPResource):
    393 
    394     method = 'post'
    395 
    396 
    397 class HTTPGet(HTTPResource):
    398 
    399     method = 'get'
    400 
    401 
    402 class HTTPPut(HTTPResource):
    403 
    404     method = 'put'
    405 
    406 
    407 class HTTPDelete(HTTPResource):
    408 
    409     method = 'delete'
    410 
    411 
    412 class HTTPTrace(HTTPResource):
    413 
    414     method = 'trace'
    415 
    416 
    417 class HTTPConnect(HTTPResource):
    418 
    419     method = 'connect'
    420 
    421 
    422 class HTTPCopy(HTTPResource):
    423 
    424     method = 'copy'
    425 
    426 
    427 class HTTPAny(HTTPResource):
    428 
    429     method = 'any'
    430 
    431 
    432 class HTTPXRefRole(XRefRole):
    433 
    434     def __init__(self, method, **kwargs):
    435         XRefRole.__init__(self, **kwargs)
    436         self.method = method
    437 
    438     def process_link(self, env, refnode, has_explicit_title, title, target):
    439         if not has_explicit_title:
    440             title = self.method.upper() + ' ' + title
    441         return title, target
    442 
    443     def result_nodes(self, document, env, node, is_ref):
    444         return [node], []
    445 
    446 
    447 class HTTPXRefMethodRole(XRefRole):
    448 
    449     def result_nodes(self, document, env, node, is_ref):
    450         method = node[0][0].lower()
    451         rawsource = node[0].rawsource
    452         config = env.domains['http'].env.config
    453         if method not in METHOD_REFS:
    454             if not config['http_strict_mode']:
    455                 return [nodes.emphasis(method, method)], []
    456             reporter = document.reporter
    457             msg = reporter.error('%s is not valid HTTP method' % method,
    458                                  line=node.line)
    459             prb = nodes.problematic(method, method)
    460             return [prb], [msg]
    461         url = str(METHOD_REFS[method])
    462         if not url:
    463             return [nodes.emphasis(method, method)], []
    464         node = nodes.reference(rawsource, method.upper(), refuri=url)
    465         return [node], []
    466 
    467 
    468 class HTTPXRefStatusRole(XRefRole):
    469 
    470     def result_nodes(self, document, env, node, is_ref):
    471         def get_code_status(text):
    472             if text.isdigit():
    473                 code = int(text)
    474                 return code, HTTP_STATUS_CODES.get(code)
    475             else:
    476                 try:
    477                     code, status = re.split(r'\s', text.strip(), 1)
    478                     code = int(code)
    479                 except ValueError:
    480                     return None, None
    481                 known_status = HTTP_STATUS_CODES.get(code)
    482                 if known_status is None:
    483                     return code, None
    484                 elif known_status.lower() != status.lower():
    485                     return code, None
    486                 else:
    487                     return code, status
    488 
    489         def report_unknown_code():
    490             if not config['http_strict_mode']:
    491                 return [nodes.emphasis(text, text)], []
    492             reporter = document.reporter
    493             msg = reporter.error('%d is unknown HTTP status code' % code,
    494                                  line=node.line)
    495             prb = nodes.problematic(text, text)
    496             return [prb], [msg]
    497 
    498         def report_invalid_code():
    499             if not config['http_strict_mode']:
    500                 return [nodes.emphasis(text, text)], []
    501             reporter = document.reporter
    502             msg = reporter.error(
    503                 'HTTP status code must be an integer (e.g. `200`) or '
    504                 'start with an integer (e.g. `200 OK`); %r is invalid' %
    505                 text,
    506                 line=node.line
    507             )
    508             prb = nodes.problematic(text, text)
    509             return [prb], [msg]
    510 
    511         text = node[0][0]
    512         rawsource = node[0].rawsource
    513         config = env.domains['http'].env.config
    514 
    515         code, status = get_code_status(text)
    516         if code is None:
    517             return report_invalid_code()
    518         elif status is None:
    519             return report_unknown_code()
    520         elif code == 449:
    521             url = 'https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-wdv/83ecf19f-e0f8-4706-aae5-ba618f52f100'
    522         elif code in HTTP_STATUS_CODES or code in WEBDAV_STATUS_CODES:
    523             url = f"https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/{code}"
    524         else:
    525             url = ''
    526         node = nodes.reference(rawsource, '%d %s' % (code, status), refuri=url)
    527         return [node], []
    528 
    529 
    530 class HTTPXRefHeaderRole(XRefRole):
    531 
    532     def result_nodes(self, document, env, node, is_ref):
    533         header = node[0][0]
    534         rawsource = node[0].rawsource
    535         if header not in HEADER_REFS:
    536             _header = '-'.join(map(lambda i: i.title(), header.split('-')))
    537             if _header not in HEADER_REFS:
    538                 return [nodes.emphasis(header, header)], []
    539         url = str(HEADER_REFS[header])
    540         node = nodes.reference(rawsource, header, refuri=url)
    541         return [node], []
    542 
    543 
    544 class HTTPIndex(Index):
    545 
    546     name = 'routingtable'
    547     localname = _('HTTP Routing Table')
    548     shortname = 'routing table'
    549 
    550     def __init__(self, *args, **kwargs):
    551         super(HTTPIndex, self).__init__(*args, **kwargs)
    552 
    553         self.ignore = [
    554             [l for l in x.split('/') if l]
    555             for x in self.domain.env.config['http_index_ignore_prefixes']]
    556         self.ignore.sort(reverse=True)
    557 
    558         # During HTML generation these values pick from class,
    559         # not from instance so we have a little hack the system
    560         cls = self.__class__
    561         cls.shortname = self.domain.env.config['http_index_shortname']
    562         cls.localname = self.domain.env.config['http_index_localname']
    563 
    564     def grouping_prefix(self, path):
    565         letters = [x for x in path.split('/') if x]
    566         for prefix in self.ignore:
    567             if letters[:len(prefix)] == prefix:
    568                 return '/' + '/'.join(letters[:len(prefix) + 1])
    569         return '/%s' % (letters[0] if letters else '',)
    570 
    571     def generate(self, docnames=None):
    572         content = {}
    573         items = ((method, path, info)
    574                  for method, routes in self.domain.routes.items()
    575                  for path, info in routes.items())
    576         items = sorted(items, key=lambda item: item[1])
    577         for method, path, info in items:
    578             entries = content.setdefault(self.grouping_prefix(path), [])
    579             entries.append([
    580                 method.upper() + ' ' + path, 0, info[0],
    581                 http_resource_anchor(method, path),
    582                 '', _('Deprecated') if info[2] else '', info[1]
    583             ])
    584         items = sorted(
    585             (path, sort_by_method(entries))
    586             for path, entries in content.items()
    587         )
    588         return (items, True)
    589 
    590 
    591 class HTTPDomain(Domain):
    592     """HTTP domain."""
    593 
    594     name = 'http'
    595     label = 'HTTP'
    596 
    597     object_types = {
    598         'options': ObjType('options', 'options'),
    599         'head': ObjType('head', 'head'),
    600         'post': ObjType('post', 'post'),
    601         'get': ObjType('get', 'get'),
    602         'put': ObjType('put', 'put'),
    603         'patch': ObjType('patch', 'patch'),
    604         'delete': ObjType('delete', 'delete'),
    605         'trace': ObjType('trace', 'trace'),
    606         'connect': ObjType('connect', 'connect'),
    607         'copy': ObjType('copy', 'copy'),
    608         'any': ObjType('any', 'any')
    609     }
    610 
    611     directives = {
    612         'options': HTTPOptions,
    613         'head': HTTPHead,
    614         'post': HTTPPost,
    615         'get': HTTPGet,
    616         'put': HTTPPut,
    617         'patch': HTTPPatch,
    618         'delete': HTTPDelete,
    619         'trace': HTTPTrace,
    620         'connect': HTTPConnect,
    621         'copy': HTTPCopy,
    622         'any': HTTPAny
    623     }
    624 
    625     roles = {
    626         'options': HTTPXRefRole('options'),
    627         'head': HTTPXRefRole('head'),
    628         'post': HTTPXRefRole('post'),
    629         'get': HTTPXRefRole('get'),
    630         'put': HTTPXRefRole('put'),
    631         'patch': HTTPXRefRole('patch'),
    632         'delete': HTTPXRefRole('delete'),
    633         'trace': HTTPXRefRole('trace'),
    634         'connect': HTTPXRefRole('connect'),
    635         'copy': HTTPXRefRole('copy'),
    636         'any': HTTPXRefRole('any'),
    637         'statuscode': HTTPXRefStatusRole(),
    638         'method': HTTPXRefMethodRole(),
    639         'header': HTTPXRefHeaderRole()
    640     }
    641 
    642     initial_data = {
    643         'options': {},  # path: (docname, synopsis)
    644         'head': {},
    645         'post': {},
    646         'get': {},
    647         'put': {},
    648         'patch': {},
    649         'delete': {},
    650         'trace': {},
    651         'connect': {},
    652         'copy': {},
    653         'any': {}
    654     }
    655 
    656     # GNUnet: no HTTP routing table index page (local change, see README).
    657     indices = []
    658 
    659     @property
    660     def routes(self):
    661         return dict((key, self.data[key]) for key in self.object_types)
    662 
    663     def clear_doc(self, docname):
    664         for typ, routes in self.routes.items():
    665             for path, info in list(routes.items()):
    666                 if info[0] == docname:
    667                     del routes[path]
    668 
    669     def resolve_xref(self, env, fromdocname, builder, typ, target,
    670                      node, contnode):
    671         try:
    672             info = self.data[str(typ)][target]
    673         except KeyError:
    674             text = contnode.rawsource
    675             role = self.roles.get(typ)
    676             if role is None:
    677                 return None
    678 
    679             reporter = LoggingReporter(env.doc2path(fromdocname),
    680                                        report_level=Reporter.WARNING_LEVEL,
    681                                        halt_level=Reporter.SEVERE_LEVEL)
    682             doctree = DummyDocument(reporter)
    683             resnode = role.result_nodes(doctree, env, node, None)[0][0]
    684             if isinstance(resnode, addnodes.pending_xref):
    685                 text = node[0][0]
    686                 reporter = doctree.reporter
    687                 reporter.warning('Cannot resolve reference to %r' % text,
    688                                  line=node.line)
    689                 return None
    690             return resnode
    691         else:
    692             anchor = http_resource_anchor(typ, target)
    693             title = typ.upper() + ' ' + target
    694             return make_refnode(builder, fromdocname, info[0], anchor,
    695                                 contnode, title)
    696 
    697     def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode):
    698         """Resolve the pending_xref *node* with the given *target*.
    699 
    700         The reference comes from an "any" or similar role, which means that Sphinx
    701         don't know the type.
    702 
    703         For now sphinxcontrib-httpdomain doesn't resolve any xref nodes.
    704 
    705         :return:
    706            list of tuples ``('domain:role', newnode)``, where ``'domain:role'``
    707            is the name of a role that could have created the same reference,
    708         """
    709         return []
    710 
    711     def get_objects(self):
    712         for method, routes in self.routes.items():
    713             for path, info in routes.items():
    714                 anchor = http_resource_anchor(method, path)
    715                 yield (path, path, method, info[0], anchor, 1)
    716 
    717     def merge_domaindata(self, docnames, otherdata):
    718         """Merge domaindata from the workers/chunks when they return.
    719 
    720         Called once per parallelization chunk.
    721         Only used when sphinx is run in parallel mode.
    722 
    723         :param docnames: a Set of the docnames that are part of the current chunk to merge
    724         :param otherdata: the partial data calculated by the current chunk
    725         """
    726         for typ in self.object_types:
    727             self_data = self.data[typ]
    728             other_data = otherdata[typ]
    729             for entry_point_name, entry_point_data in other_data.items():
    730                 if entry_point_name in self_data and entry_point_data != self_data[entry_point_name]:
    731                     logger.warning('duplicate HTTP %s method definition %s in %s, '
    732                                    'other instance is in %s' %
    733                                    (typ, entry_point_name,
    734                                     self.env.doc2path(other_data[entry_point_name][0]),
    735                                     self.env.doc2path(self_data[entry_point_name][0])))
    736                 else:
    737                     self_data[entry_point_name] = entry_point_data
    738 
    739 class HTTPLexer(RegexLexer):
    740     """Lexer for HTTP sessions."""
    741 
    742     name = 'HTTP'
    743     aliases = ['http']
    744 
    745     flags = re.DOTALL
    746 
    747     def header_callback(self, match):
    748         if match.group(1).lower() == 'content-type':
    749             content_type = match.group(5).strip()
    750             if ';' in content_type:
    751                 content_type = content_type[:content_type.find(';')].strip()
    752             self.content_type = content_type
    753         yield match.start(1), Name.Attribute, match.group(1)
    754         yield match.start(2), Text, match.group(2)
    755         yield match.start(3), Operator, match.group(3)
    756         yield match.start(4), Text, match.group(4)
    757         yield match.start(5), Literal, match.group(5)
    758         yield match.start(6), Text, match.group(6)
    759 
    760     def continuous_header_callback(self, match):
    761         yield match.start(1), Text, match.group(1)
    762         yield match.start(2), Literal, match.group(2)
    763         yield match.start(3), Text, match.group(3)
    764 
    765     def content_callback(self, match):
    766         content_type = getattr(self, 'content_type', None)
    767         content = match.group()
    768         offset = match.start()
    769         if content_type:
    770             from pygments.lexers import get_lexer_for_mimetype
    771             try:
    772                 lexer = get_lexer_for_mimetype(content_type)
    773             except ClassNotFound:
    774                 pass
    775             else:
    776                 for idx, token, value in lexer.get_tokens_unprocessed(content):
    777                     yield offset + idx, token, value
    778                 return
    779         yield offset, Text, content
    780 
    781     tokens = {
    782         'root': [
    783             (r'(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE|COPY)( +)([^ ]+)( +)'
    784              r'(HTTPS?)(/)(1\.[01])(\r?\n|$)',
    785              bygroups(Name.Function, Text, Name.Namespace, Text,
    786                       Keyword.Reserved, Operator, Number, Text),
    787              'headers'),
    788             (r'(HTTPS?)(/)(1\.[01])( +)(\d{3})( +)([^\r\n]+)(\r?\n|$)',
    789              bygroups(Keyword.Reserved, Operator, Number, Text, Number,
    790                       Text, Name.Exception, Text),
    791              'headers'),
    792         ],
    793         'headers': [
    794             (r'([^\s:]+)( *)(:)( *)([^\r\n]+)(\r?\n|$)', header_callback),
    795             (r'([\t ]+)([^\r\n]+)(\r?\n|$)', continuous_header_callback),
    796             (r'\r?\n', Text, 'content')
    797         ],
    798         'content': [
    799             (r'.+', content_callback)
    800         ]
    801     }
    802 
    803 
    804 def register_routingtable_as_label(app, document):
    805     labels = app.env.domaindata['std']['labels']
    806     labels['routingtable'] = 'http-routingtable', '', _('HTTP Routing Table')
    807     anonlabels = app.env.domaindata['std']['anonlabels']
    808     anonlabels['routingtable'] = 'http-routingtable', ''
    809 
    810 
    811 def setup(app):
    812     app.add_domain(HTTPDomain)
    813     app.add_domain(WebSocketDomain)
    814     app.connect('doctree-read', register_routingtable_as_label)
    815 
    816     package_dir = os.path.abspath(os.path.dirname(__file__))
    817     locale_dir = os.path.join(package_dir, 'locale')
    818     app.add_message_catalog('httpdomain', locale_dir)
    819 
    820     try:
    821         get_lexer_by_name('http')
    822     except ClassNotFound:
    823         app.add_lexer('http', HTTPLexer())
    824     app.add_config_value('http_index_ignore_prefixes', [], None)
    825     app.add_config_value('http_index_shortname', 'routing table', True)
    826     app.add_config_value('http_index_localname', _('HTTP Routing Table'), True)
    827     app.add_config_value('http_strict_mode', True, None)
    828     app.add_config_value('http_headers_ignore_prefixes', ['X-'], None)
    829     return {"parallel_read_safe": True,
    830             "parallel_write_safe": True}