Mercurial: mercurial/templater.py comparison

comparison mercurial/templater.py @ 24586:90e3f5d22dad

templater: add consistent docstrings to functions The content of "hg help templating" is largely derived from docstrings on functions providing functionality. Template functions are the long holdout. Prepare for generating them dynamically by defining docstrings for all template functions. There are numerous ways these docs could be improved. Right now, the help output simply shows function names and arguments. So literally any accurate data is better than what is there now.

author	Gregory Szorc <gregory.szorc@gmail.com>
date	Wed, 01 Apr 2015 20:19:43 -0700
parents	696ab1a24ae0
children	d80819f67d59

comparison

equal deleted inserted replaced

-:e191d5d8d515
+:90e3f5d22dad
 f = context._filters[n]
 return (runfilter, (args[0][0], args[0][1], f))
 raise error.ParseError(_("unknown function '%s'") % n)
 def date(context, mapping, args):
+""":date(date[, fmt]): Format a date. See :hg:`help dates` for formatting
+strings."""
 if not (1 <= len(args) <= 2):
 # i18n: "date" is a keyword
 raise error.ParseError(_("date expects one or two arguments"))
 date = args[0][0](context, mapping, args[0][1])
 fmt = stringify(args[1][0](context, mapping, args[1][1]))
 return util.datestr(date, fmt)
 return util.datestr(date)
 def diff(context, mapping, args):
+""":diff([includepattern [, excludepattern]]): Show a diff, optionally
+specifying files to include or exclude."""
 if len(args) > 2:
 # i18n: "diff" is a keyword
 raise error.ParseError(_("diff expects one, two or no arguments"))
 def getpatterns(i):
 chunks = ctx.diff(match=ctx.match([], getpatterns(0), getpatterns(1)))
 return ''.join(chunks)
 def fill(context, mapping, args):
+""":fill(text[, width[, initialident[, hangindent]]]): Fill many
+paragraphs with optional indentation. See the "fill" filter."""
 if not (1 <= len(args) <= 4):
 # i18n: "fill" is a keyword
 raise error.ParseError(_("fill expects one to four arguments"))
 text = stringify(args[0][0](context, mapping, args[0][1]))
 pass
 return templatefilters.fill(text, width, initindent, hangindent)
 def pad(context, mapping, args):
-"""usage: pad(text, width, fillchar=' ', right=False)
+""":pad(text, width[, fillchar=' '[, right=False]]): Pad text with a
-"""
+fill character."""
 if not (2 <= len(args) <= 4):
 # i18n: "pad" is a keyword
 raise error.ParseError(_("pad() expects two to four arguments"))
 width = int(args[1][1])
 return text.rjust(width, fillchar)
 else:
 return text.ljust(width, fillchar)
 def get(context, mapping, args):
+""":get(dict, key): Get an attribute/key from an object. Some keywords
+are complex types. This function allows you to obtain the value of an
+attribute on these type."""
 if len(args) != 2:
 # i18n: "get" is a keyword
 raise error.ParseError(_("get() expects two arguments"))
 dictarg = args[0][0](context, mapping, args[0][1])
 compiletemplate(t, context, strtoken='rawstring'))
 else:
 yield t
 def if_(context, mapping, args):
+""":if(expr, then[, else]): Conditionally execute based on the result of
+an expression."""
 if not (2 <= len(args) <= 3):
 # i18n: "if" is a keyword
 raise error.ParseError(_("if expects two or three arguments"))
 test = stringify(args[0][0](context, mapping, args[0][1]))
 yield _evalifliteral(args[1], context, mapping)
 elif len(args) == 3:
 yield _evalifliteral(args[2], context, mapping)
 def ifcontains(context, mapping, args):
+""":ifcontains(search, thing, then[, else]): Conditionally execute based
+on whether the item "search" is in "thing"."""
 if not (3 <= len(args) <= 4):
 # i18n: "ifcontains" is a keyword
 raise error.ParseError(_("ifcontains expects three or four arguments"))
 item = stringify(args[0][0](context, mapping, args[0][1]))
 yield _evalifliteral(args[2], context, mapping)
 elif len(args) == 4:
 yield _evalifliteral(args[3], context, mapping)
 def ifeq(context, mapping, args):
+""":ifeq(expr1, expr2, then[, else]): Conditionally execute based on
+whether 2 items are equivalent."""
 if not (3 <= len(args) <= 4):
 # i18n: "ifeq" is a keyword
 raise error.ParseError(_("ifeq expects three or four arguments"))
 test = stringify(args[0][0](context, mapping, args[0][1]))
 yield _evalifliteral(args[2], context, mapping)
 elif len(args) == 4:
 yield _evalifliteral(args[3], context, mapping)
 def join(context, mapping, args):
+""":join(list, sep): Join items in a list with a delimiter."""
 if not (1 <= len(args) <= 2):
 # i18n: "join" is a keyword
 raise error.ParseError(_("join expects one or two arguments"))
 joinset = args[0][0](context, mapping, args[0][1])
 else:
 yield joiner
 yield x
 def label(context, mapping, args):
+""":label(label, expr): Apply a label to generated content. Content with
+a label applied can result in additional post-processing, such as
+automatic colorization."""
 if len(args) != 2:
 # i18n: "label" is a keyword
 raise error.ParseError(_("label expects two arguments"))
 # ignore args[0] (the label string) since this is supposed to be a a no-op
 yield _evalifliteral(args[1], context, mapping)
 def revset(context, mapping, args):
-"""usage: revset(query[, formatargs...])
+""":revset(query[, formatargs...]): Execute a revision set query. See
-"""
+:hg:`help revset`."""
 if not len(args) > 0:
 # i18n: "revset" is a keyword
 raise error.ParseError(_("revset expects one or more arguments"))
 raw = args[0][1]
 revsetcache[raw] = revs
 return templatekw.showlist("revision", revs, **mapping)
 def rstdoc(context, mapping, args):
+""":rstdoc(text, style): Format ReStructuredText."""
 if len(args) != 2:
 # i18n: "rstdoc" is a keyword
 raise error.ParseError(_("rstdoc expects two arguments"))
 text = stringify(args[0][0](context, mapping, args[0][1]))
 style = stringify(args[1][0](context, mapping, args[1][1]))
 return minirst.format(text, style=style, keep=['verbose'])
 def shortest(context, mapping, args):
-"""usage: shortest(node, minlength=4)
+""":shortest(node, minlength=4): Obtain the shortest representation of
-"""
+a node."""
 if not (1 <= len(args) <= 2):
 # i18n: "shortest" is a keyword
 raise error.ParseError(_("shortest() expects one or two arguments"))
 node = stringify(args[0][0](context, mapping, args[0][1]))
 length += 1
 if len(shortest) <= length:
 return shortest
 def strip(context, mapping, args):
+""":strip(text[, chars]): Strip characters from a string."""
 if not (1 <= len(args) <= 2):
 # i18n: "strip" is a keyword
 raise error.ParseError(_("strip expects one or two arguments"))
 text = stringify(args[0][0](context, mapping, args[0][1]))
 chars = stringify(args[1][0](context, mapping, args[1][1]))
 return text.strip(chars)
 return text.strip()
 def sub(context, mapping, args):
+""":sub(pattern, replacement, expression): Perform text substitution
+using regular expressions."""
 if len(args) != 3:
 # i18n: "sub" is a keyword
 raise error.ParseError(_("sub expects three arguments"))
 pat = stringify(args[0][0](context, mapping, args[0][1]))
 rpl = stringify(args[1][0](context, mapping, args[1][1]))
 src = stringify(_evalifliteral(args[2], context, mapping))
 yield re.sub(pat, rpl, src)
 def startswith(context, mapping, args):
+""":startswith(pattern, text): Returns the value from the "text" argument
+if it begins with the content from the "pattern" argument."""
 if len(args) != 2:
 # i18n: "startswith" is a keyword
 raise error.ParseError(_("startswith expects two arguments"))
 patn = stringify(args[0][0](context, mapping, args[0][1]))
 return text
 return ''
 def word(context, mapping, args):
-"""return nth word from a string"""
+""":word(number, text[, separator]): Return the nth word from a string."""
 if not (2 <= len(args) <= 3):
 # i18n: "word" is a keyword
 raise error.ParseError(_("word expects two or three arguments, got %d")
 % len(args))

Mercurial > hg

comparison mercurial/templater.py @ 24586:90e3f5d22dad