# HG changeset patch # User Gregory Szorc # Date 2015-04-02 03:19:43 # Node ID 90e3f5d22dad550b97c1fd9153a1be76c4b1509e # Parent e191d5d8d5158b9901e12d593638dc29a76b7836 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. diff --git a/mercurial/templater.py b/mercurial/templater.py --- a/mercurial/templater.py +++ b/mercurial/templater.py @@ -219,6 +219,8 @@ def buildfunc(exp, context): 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")) @@ -230,6 +232,8 @@ def date(context, mapping, args): 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")) @@ -247,6 +251,8 @@ def diff(context, mapping, args): 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")) @@ -270,8 +276,8 @@ def fill(context, mapping, args): 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")) @@ -296,6 +302,9 @@ def pad(context, mapping, args): 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")) @@ -317,6 +326,8 @@ def _evalifliteral(arg, context, mapping 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")) @@ -328,6 +339,8 @@ def if_(context, mapping, args): 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")) @@ -341,6 +354,8 @@ def ifcontains(context, mapping, args): 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")) @@ -353,6 +368,7 @@ def ifeq(context, mapping, args): 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")) @@ -375,6 +391,9 @@ def join(context, mapping, args): 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")) @@ -383,8 +402,8 @@ def label(context, mapping, args): 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")) @@ -413,6 +432,7 @@ def revset(context, mapping, args): 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")) @@ -423,8 +443,8 @@ def rstdoc(context, mapping, args): 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")) @@ -475,6 +495,7 @@ def shortest(context, mapping, args): 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")) @@ -486,6 +507,8 @@ def strip(context, mapping, args): 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")) @@ -496,6 +519,8 @@ def sub(context, mapping, args): 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")) @@ -508,7 +533,7 @@ def startswith(context, mapping, args): 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")