commit f490844a07c6a6dc9b37e466992b7f196de0719b Author: Damian Johnson atagar@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/%7Bticket%7D' +TOR_TICKET_URL = 'https://gitlab.torproject.org/tpo/core/tor/-/issues/%7Bticket%7D' TRAC_URL = 'https://trac.torproject.org/%7Bticket%7D' SPEC_URL = 'https://gitweb.torproject.org/torspec.git/commit/?id=%7Bcommit%7D'

+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