docs/roles.py

   1 import re
   2
   3 from docutils.nodes import reference
   4
   5 STEM_TICKET_URL = 'https://github.com/torproject/stem/issues/{ticket}'
   6 TOR_TICKET_URL = 'https://gitlab.torproject.org/tpo/core/tor/-/issues/{ticket}'
   7 ARCHIVE_TICKET_URL = 'https://gitlab.torproject.org/legacy/trac/-/issues/{ticket}'
   8 SPEC_URL = 'https://gitweb.torproject.org/torspec.git/commit/?id={commit}'
   9
  10
  11 def role_ticket(name, rawtext, argument, lineno, inliner, options = {}, content = []):
  12   """
  13   Alias :ticket:`1234` or :ticket:`tor-1234` to a link for that ticket. Tickets
  14   default to be for Stem if no project is indicated.
  15   """
  16
  17   if '-' in argument:
  18     project, ticket = argument.split('-', 1)
  19   else:
  20     project, ticket = 'stem', argument
  21
  22   if not ticket.isdigit() or int(ticket) <= 0:
  23     return error('Invalid ticket number: %s' % ticket, rawtext, lineno, inliner)
  24
  25   if project == 'stem':
  26     label = 'ticket %s' % ticket
  27     url = STEM_TICKET_URL.format(ticket = ticket)
  28   elif project == 'archive':
  29     label = 'ticket %s' % ticket
  30     url = ARCHIVE_TICKET_URL.format(ticket = ticket)
  31   elif project == 'tor':
  32     label = 'tor ticket %s' % ticket
  33     url = TOR_TICKET_URL.format(ticket = ticket)
  34   else:
  35     return error('Project %s is unrecognized: %s' % (project, argument), rawtext, lineno, inliner)
  36
  37   return (
  38     [reference(rawtext, label, refuri = url, **options)],
  39     [],
  40   )
  41
  42
  43 def role_spec(name, rawtext, argument, lineno, inliner, options = {}, content = []):
  44   """
  45   Aliases :spec:`25b0d43` to 'https://gitweb.torproject.org/torspec.git/commit/?id=25b0d43'.
  46   """
  47
  48   if not re.match('^[0-9a-f]{7}$', argument):
  49     return error('Spec tag expects a short commit id (seven hex characters): %s' % argument, rawtext, lineno, inliner)
  50
  51   return (
  52     [reference(rawtext, 'spec', refuri = SPEC_URL.format(commit = argument), **options)],
  53     [],
  54   )
  55
  56
  57 def error(message, rawtext, lineno, inliner):
  58   msg = inliner.reporter.error(message, line = lineno)
  59   prb = inliner.problematic(rawtext, rawtext, msg)
  60
  61   return ([prb], [msg])
  62
  63
  64 def setup(app):
  65   """
  66   Installs the plugin.
  67
  68   :param app: sphinx application context
  69   """
  70
  71   app.add_role('ticket', role_ticket)
  72   app.add_role('spec', role_spec)