commit 4bdcba090b5a29e2a64c229a5ba9246ddbb59a69 Author: Damian Johnson atagar@torproject.org Date: Sun Apr 14 16:05:03 2013 -0700

Style revisions

Our trac.py is based on an external tutorial...

http://doughellmann.com/2010/05/defining-custom-roles-in-sphinx.html

As such it naturally had different stylistic conventions from stem. There were also some minor points that had some room for simplification. --- docs/republish.py | 25 ++++++----- docs/trac.py | 121 +++++++++++++++++++++++++++-------------------------- 2 files changed, 75 insertions(+), 71 deletions(-)

diff --git a/docs/republish.py b/docs/republish.py index 0dbad16..ae783cf 100644 --- a/docs/republish.py +++ b/docs/republish.py @@ -24,40 +24,43 @@ If stem's repository is unchanged then this is a no-op. -r, --repeat RATE tries to republish the site at a set rate, in minutes """

+ def run(command, cwd = None): # Runs the given command. This returns the stdout if successful, and raises # an OSError if it fails. - + cmd = subprocess.Popen(command.split(' '), stdout = subprocess.PIPE, stderr = subprocess.PIPE, cwd = cwd) - + if cmd.wait() == 0: return cmd.communicate()[0] else: stdout, stderr = cmd.communicate() raise OSError("'%s' failed\n stdout: %s\n stderr: %s" % (command, stdout.strip(), stderr.strip()))

+ def republish_site(): # Checks if stem's repository has changed, rebuilding the site if so. Ideally # we'd use plumbing commands to check this but... meh. Patches welcome. - + if 'Already up-to-date.' not in run('git pull', cwd = '/home/stem/stem'): start_time = time.time() LOGGER.log(logging.INFO, "Stem's repository has changed. Republishing...") run('make html', cwd = '/home/stem/stem/docs') run('sudo -u mirroradm static-master-update-component stem.torproject.org') - + runtime = int(time.time() - start_time) LOGGER.log(logging.INFO, " site republished (took %s seconds)" % runtime)

+ if __name__ == '__main__': - try: + try: opts = getopt.getopt(sys.argv[1:], OPT, OPT_EXPANDED)[0] except getopt.GetoptError, exc: print "%s (for usage provide --help)" % exc sys.exit(1) - + repeat_rate = None - + for opt, arg in opts: if opt in ("-r", "--repeat"): if arg.isdigit(): @@ -68,15 +71,15 @@ if __name__ == '__main__': elif opt in ("-h", "--help"): print HELP_MSG sys.exit() - + if repeat_rate: LOGGER.log(logging.INFO, "Starting stem site republisher") - latest_run = 0 # unix timestamp for when we last ran - + latest_run = 0 # unix timestamp for when we last ran + while True: while time.time() < (latest_run + repeat_rate * 60): time.sleep(15) - + try: latest_run = time.time() republish_site() diff --git a/docs/trac.py b/docs/trac.py index d2459dd..7af5440 100644 --- a/docs/trac.py +++ b/docs/trac.py @@ -4,68 +4,69 @@ from docutils.parsers.rst.roles import set_classes

def role_trac(name, rawtext, text, lineno, inliner, options={}, content=[]): - """Returns two part tuple consisting of node and system messages. - Both allowed to be empty. - - :param name: The role name used in the document. - :param rawtext: The entire markup snippet, with role. - :param text: The text marked with the role. - :param lineno: The line number where rawtext appears in the input. - :param inliner: The inliner instance that called us. - :param options: Directive options for customization. - :param content: The directive content for customization. - """ - - # checking if the number is valid - try: - ticket_num = int(text) - if ticket_num <= 0: - raise ValueError - - except ValueError: - msg = inliner.reporter.error( - 'Invalid trac ticket: %s' % (text), line=lineno) - prb = inliner.problematic(rawtext, rawtext, msg) - return ([prb], [msg]) - - app = inliner.document.settings.env.app - node = make_link_node(rawtext, app, 'ticket', str(ticket_num), options) - return ([node], []) - - -def make_link_node(rawtext, app, type, slug, options): - """Creates a link to a trac ticket. - - :param rawtext: Text being replaced with link node. - :param app: Sphinx application context - :param type: Link type (issue, changeset, etc.) - :param slug: ID of the thing to link to - :param options: Options dictionary passed to role func. - """ - - # checking if trac_url is set in conf.py - try: - base = app.config.trac_url - if not base: - raise AttributeError - - except AttributeError, e: - raise ValueError('trac_url is not set (%s)' % str(e)) - - slash = '/' if base[-1] != '/' else '' - ref = base + slash + slug - set_classes(options) - name = type + ' ' + unescape(slug) - node = reference(rawtext, name, refuri=ref, **options) - return node + """ + Returns two part tuple consisting of node and system messages. Both allowed + to be empty. + + :param name: the role name used in the document + :param rawtext: the entire markup snippet, with role + :param text: the text marked with the role + :param lineno: the line number where rawtext appears in the input + :param inliner: the inliner instance that called us + :param options: directive options for customization + :param content: the directive content for customization + """ + + # checking if the number is valid + try: + ticket_num = int(text) + + if ticket_num <= 0: + raise ValueError + except ValueError: + msg = inliner.reporter.error( + 'Invalid trac ticket: %s' % (text), line=lineno) + prb = inliner.problematic(rawtext, rawtext, msg) + + return ([prb], [msg]) + + app = inliner.document.settings.env.app + + return ( + [make_link_node(rawtext, app, 'ticket', str(ticket_num), options)], + [], + ) + + +def make_link_node(rawtext, app, link_type, slug, options): + """ + Creates a link to a trac ticket. + + :param rawtext: text being replaced with link node + :param app: sphinx application context + :param link_type: link type (issue, changeset, etc.) + :param slug: ID of the thing to link to + :param options: options dictionary passed to role func + """ + + trac_base_url = getattr(app.config, 'trac_url', None) + + if not trac_base_url: + raise ValueError('trac_url is not set') + + ref = trac_base_url.rstrip('/') + '/' + slug + set_classes(options) + name = link_type + ' ' + unescape(slug) # sets the text to 'ticket 345' + + return reference(rawtext, name, refuri = ref, **options)

def setup(app): - """Installs the plugin. + """ + Installs the plugin.

- :param app: Sphinx application context. - """ + :param app: sphinx application context + """

- app.add_role('trac', role_trac) - app.add_config_value('trac_url', None, 'env') - return + app.add_role('trac', role_trac) + app.add_config_value('trac_url', None, 'env')