[tor-commits] [stem/master] Add a 'ticket' sphinx role

[atagar at torproject.org]

commit f490844a07c6a6dc9b37e466992b7f196de0719b
Author: Damian Johnson <atagar at torproject.org>
Date:   Sun Aug 16 14:03:27 2020 -0700

    Add a 'ticket' sphinx role
    
    Adding a role so we can cite stem and tor tickets on their new bug trackers.
---
 docs/roles.py   | 49 +++++++++++++++++++++++++++++++++++++++++--------
 stem/control.py |  2 +-
 2 files changed, 42 insertions(+), 9 deletions(-)

diff --git a/docs/roles.py b/docs/roles.py
index fcec7e9d..c7f883e8 100644
--- a/docs/roles.py
+++ b/docs/roles.py
@@ -4,20 +4,48 @@ from docutils.utils import unescape
 from docutils.nodes import reference
 from docutils.parsers.rst.roles import set_classes
 
+STEM_TICKET_URL = 'https://github.com/torproject/stem/issues/{ticket}'
+TOR_TICKET_URL = 'https://gitlab.torproject.org/tpo/core/tor/-/issues/{ticket}'
 TRAC_URL = 'https://trac.torproject.org/{ticket}'
 SPEC_URL = 'https://gitweb.torproject.org/torspec.git/commit/?id={commit}'
 
 
+def role_ticket(name, rawtext, argument, lineno, inliner, options = {}, content = []):
+  """
+  Alias :ticket:`1234` or :ticket:`tor-1234` to a link for that ticket. Tickets
+  default to be for Stem if no project is indicated.
+  """
+
+  if '-' in argument:
+    project, ticket = argument.split('-', 1)
+  else:
+    project, ticket = 'stem', argument
+
+  if not ticket.isdigit() or int(ticket) <= 0:
+    return error('Invalid ticket number: %s' % ticket, rawtext, lineno, inliner)
+
+  if project == 'stem':
+    label = 'ticket %s' % ticket
+    url = STEM_TICKET_URL.format(ticket = ticket)
+  elif project == 'tor':
+    label = 'tor ticket %s' % ticket
+    url = TOR_TICKET_URL.format(ticket = ticket)
+  else:
+    return error('Project %s is unrecognized: %s' % (project, argument), rawtext, lineno, inliner)
+
+  return (
+    [reference(rawtext, label, refuri = url, **options)],
+    [],
+  )
+
+
 def role_trac(name, rawtext, argument, lineno, inliner, options = {}, content = []):
   """
   Aliases :trac:`1234` to 'https://trac.torproject.org/1234'.
   """
 
   if not argument.isdigit() or int(argument) <= 0:
-    return (
-      [inliner.problematic(rawtext, rawtext, msg)],
-      [inliner.reporter.error('Invalid trac ticket: %s' % argument, line = lineno)],
-    )
+    return error('Invalid ticket number: %s' % argument, rawtext, lineno, inliner)
 
   return (
     [reference(rawtext, 'ticket %s' % argument, refuri = TRAC_URL.format(ticket = argument), **options)],
@@ -31,10 +59,7 @@ def role_spec(name, rawtext, argument, lineno, inliner, options = {}, content =
   """
 
   if not re.match('^[0-9a-f]{7}$', argument):
-    return (
-      [inliner.problematic(rawtext, rawtext, msg)],
-      [inliner.reporter.error('Spec tag expects a short commit id (seven hex characters): %s' % argument, line = lineno)],
-    )
+    return error('Spec tag expects a short commit id (seven hex characters): %s' % argument, rawtext, lineno, inliner)
 
   return (
     [reference(rawtext, 'spec', refuri = SPEC_URL.format(commit = argument), **options)],
@@ -42,6 +67,13 @@ def role_spec(name, rawtext, argument, lineno, inliner, options = {}, content =
   )
 
 
+def error(message, rawtext, lineno, inliner):
+  msg = inliner.reporter.error(message, line = lineno)
+  prb = inliner.problematic(rawtext, rawtext, msg)
+
+  return ([prb], [msg])
+
+
 def setup(app):
   """
   Installs the plugin.
@@ -49,5 +81,6 @@ def setup(app):
   :param app: sphinx application context
   """
 
+  app.add_role('ticket', role_ticket)
   app.add_role('trac', role_trac)
   app.add_role('spec', role_spec)
diff --git a/stem/control.py b/stem/control.py
index e1c68ce9..dfd764ba 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -2935,7 +2935,7 @@ class Controller(BaseController):
 
     Please note that **basic_auth** only works for legacy (v2) hidden services.
     Version 3 can't enable service authentication through the control protocol
-    (`ticket <https://gitlab.torproject.org/tpo/core/tor/-/issues/40084>`_).
+    (:ticket:`tor-40084`).
 
     To create a **version 3** service simply specify **ED25519-V3** as the
     our key type, and to create a **version 2** service use **RSA1024**. The