Mercurial > hg-stable
changeset 13591:264f292a0c6f
templatefilters: move doc from templates.txt to docstrings
| author | Patrick Mezard <pmezard@gmail.com> |
|---|---|
| date | Sat, 12 Mar 2011 12:46:31 +0100 |
| parents | 1a752dcfe062 |
| children | ad2ee188f4a5 |
| files | mercurial/commands.py mercurial/help/templates.txt mercurial/templatefilters.py |
| diffstat | 3 files changed, 93 insertions(+), 87 deletions(-) [+] |
line wrap: on
line diff
--- a/mercurial/commands.py Sat Mar 12 12:46:31 2011 +0100 +++ b/mercurial/commands.py Sat Mar 12 12:46:31 2011 +0100 @@ -13,7 +13,7 @@ import patch, help, mdiff, url, encoding, templatekw, discovery import archival, changegroup, cmdutil, sshserver, hbisect, hgweb, hgweb.server import merge as mergemod -import minirst, revset +import minirst, revset, templatefilters import dagparser # Commands start here, listed alphabetically @@ -2143,6 +2143,7 @@ help.addtopichook('revsets', revset.makedoc) help.addtopichook('templates', templatekw.makedoc) + help.addtopichook('templates', templatefilters.makedoc) if name and name != 'shortlist': i = None
--- a/mercurial/help/templates.txt Sat Mar 12 12:46:31 2011 +0100 +++ b/mercurial/help/templates.txt Sat Mar 12 12:46:31 2011 +0100 @@ -37,82 +37,4 @@ List of filters: -:addbreaks: Any text. Add an XHTML "<br />" tag before the end of - every line except the last. - -:age: Date. Returns a human-readable date/time difference between the - given date/time and the current date/time. - -:basename: Any text. Treats the text as a path, and returns the last - component of the path after splitting by the path separator - (ignoring trailing separators). For example, "foo/bar/baz" becomes - "baz" and "foo/bar//" becomes "bar". - -:stripdir: Treat the text as path and strip a directory level, if - possible. For example, "foo" and "foo/bar" becomes "foo". - -:date: Date. Returns a date in a Unix date format, including the - timezone: "Mon Sep 04 15:13:13 2006 0700". - -:domain: Any text. Finds the first string that looks like an email - address, and extracts just the domain component. Example: ``User - <user@example.com>`` becomes ``example.com``. - -:email: Any text. Extracts the first string that looks like an email - address. Example: ``User <user@example.com>`` becomes - ``user@example.com``. - -:escape: Any text. Replaces the special XML/XHTML characters "&", "<" - and ">" with XML entities. - -:hex: Any text. Convert a binary Mercurial node identifier into - its long hexadecimal representation. - -:fill68: Any text. Wraps the text to fit in 68 columns. - -:fill76: Any text. Wraps the text to fit in 76 columns. - -:firstline: Any text. Returns the first line of text. - -:nonempty: Any text. Returns '(none)' if the string is empty. - -:hgdate: Date. Returns the date as a pair of numbers: "1157407993 - 25200" (Unix timestamp, timezone offset). - -:isodate: Date. Returns the date in ISO 8601 format: "2009-08-18 13:00 - +0200". - -:isodatesec: Date. Returns the date in ISO 8601 format, including - seconds: "2009-08-18 13:00:13 +0200". See also the rfc3339date - filter. - -:localdate: Date. Converts a date to local date. - -:obfuscate: Any text. Returns the input text rendered as a sequence of - XML entities. - -:person: Any text. Returns the text before an email address. - -:rfc822date: Date. Returns a date using the same format used in email - headers: "Tue, 18 Aug 2009 13:00:13 +0200". - -:rfc3339date: Date. Returns a date using the Internet date format - specified in RFC 3339: "2009-08-18T13:00:13+02:00". - -:short: Changeset hash. Returns the short form of a changeset hash, - i.e. a 12 hexadecimal digit string. - -:shortdate: Date. Returns a date like "2006-09-18". - -:stringify: Any type. Turns the value into text by converting values into - text and concatenating them. - -:strip: Any text. Strips all leading and trailing whitespace. - -:tabindent: Any text. Returns the text, with every line except the - first starting with a tab character. - -:urlescape: Any text. Escapes all "special" characters. For example, - "foo bar" becomes "foo%20bar". - -:user: Any text. Returns the user portion of an email address. +.. filtersmarker
--- a/mercurial/templatefilters.py Sat Mar 12 12:46:31 2011 +0100 +++ b/mercurial/templatefilters.py Sat Mar 12 12:46:31 2011 +0100 @@ -7,9 +7,12 @@ import cgi, re, os, time, urllib import encoding, node, util +from i18n import gettext def addbreaks(text): - '''replace raw newlines with xhtml line breaks.''' + """:addbreaks: Any text. Add an XHTML "<br />" tag before the end of + every line except the last. + """ return text.replace('\n', '<br/>\n') agescales = [("year", 3600 * 24 * 365), @@ -21,7 +24,9 @@ ("second", 1)] def age(date): - '''turn a (timestamp, tzoff) tuple into an age string.''' + """:age: Date. Returns a human-readable date/time difference between the + given date/time and the current date/time. + """ def plural(t, c): if c == 1: @@ -45,13 +50,24 @@ return '%s ago' % fmt(t, n) def basename(path): + """:basename: Any text. Treats the text as a path, and returns the last + component of the path after splitting by the path separator + (ignoring trailing separators). For example, "foo/bar/baz" becomes + "baz" and "foo/bar//" becomes "bar". + """ return os.path.basename(path) def datefilter(text): + """:date: Date. Returns a date in a Unix date format, including the + timezone: "Mon Sep 04 15:13:13 2006 0700". + """ return util.datestr(text) def domain(author): - '''get domain of author, or empty string if none.''' + """:domain: Any text. Finds the first string that looks like an email + address, and extracts just the domain component. Example: ``User + <user@example.com>`` becomes ``example.com``. + """ f = author.find('@') if f == -1: return '' @@ -62,9 +78,16 @@ return author def email(text): + """:email: Any text. Extracts the first string that looks like an email + address. Example: ``User <user@example.com>`` becomes + ``user@example.com``. + """ return util.email(text) def escape(text): + """:escape: Any text. Replaces the special XML/XHTML characters "&", "<" + and ">" with XML entities. + """ return cgi.escape(text, True) para_re = None @@ -96,28 +119,43 @@ for para, rest in findparas()]) def fill68(text): + """:fill68: Any text. Wraps the text to fit in 68 columns.""" return fill(text, 68) def fill76(text): + """:fill76: Any text. Wraps the text to fit in 76 columns.""" return fill(text, 76) def firstline(text): - '''return the first line of text''' + """:firstline: Any text. Returns the first line of text.""" try: return text.splitlines(True)[0].rstrip('\r\n') except IndexError: return '' def hexfilter(text): + """:hex: Any text. Convert a binary Mercurial node identifier into + its long hexadecimal representation. + """ return node.hex(text) def hgdate(text): + """:hgdate: Date. Returns the date as a pair of numbers: "1157407993 + 25200" (Unix timestamp, timezone offset). + """ return "%d %d" % text def isodate(text): + """:isodate: Date. Returns the date in ISO 8601 format: "2009-08-18 13:00 + +0200". + """ return util.datestr(text, '%Y-%m-%d %H:%M %1%2') def isodatesec(text): + """:isodatesec: Date. Returns the date in ISO 8601 format, including + seconds: "2009-08-18 13:00:13 +0200". See also the rfc3339date + filter. + """ return util.datestr(text, '%Y-%m-%d %H:%M:%S %1%2') def indent(text, prefix): @@ -176,12 +214,17 @@ return ''.join(_uescape(c) for c in s) def localdate(text): + """:localdate: Date. Converts a date to local date.""" return (text[0], util.makedate()[1]) def nonempty(str): + """:nonempty: Any text. Returns '(none)' if the string is empty.""" return str or "(none)" def obfuscate(text): + """:obfuscate: Any text. Returns the input text rendered as a sequence of + XML entities. + """ text = unicode(text, encoding.encoding, 'replace') return ''.join(['&#%d;' % ord(c) for c in text]) @@ -193,7 +236,7 @@ return "-rw-r--r--" def person(author): - '''get name of author, or else username.''' + """:person: Any text. Returns the text before an email address.""" if not '@' in author: return author f = author.find('<') @@ -202,31 +245,46 @@ return author[:f].rstrip() def rfc3339date(text): + """:rfc3339date: Date. Returns a date using the Internet date format + specified in RFC 3339: "2009-08-18T13:00:13+02:00". + """ return util.datestr(text, "%Y-%m-%dT%H:%M:%S%1:%2") def rfc822date(text): + """:rfc822date: Date. Returns a date using the same format used in email + headers: "Tue, 18 Aug 2009 13:00:13 +0200". + """ return util.datestr(text, "%a, %d %b %Y %H:%M:%S %1%2") def short(text): + """:short: Changeset hash. Returns the short form of a changeset hash, + i.e. a 12 hexadecimal digit string. + """ return text[:12] def shortdate(text): + """:shortdate: Date. Returns a date like "2006-09-18".""" return util.shortdate(text) def stringescape(text): return text.encode('string_escape') def stringify(thing): - '''turn nested template iterator into string.''' + """:stringify: Any type. Turns the value into text by converting values into + text and concatenating them. + """ if hasattr(thing, '__iter__') and not isinstance(thing, str): return "".join([stringify(t) for t in thing if t is not None]) return str(thing) def strip(text): + """:strip: Any text. Strips all leading and trailing whitespace.""" return text.strip() def stripdir(text): - '''Treat the text as path and strip a directory level, if possible.''' + """:stripdir: Treat the text as path and strip a directory level, if + possible. For example, "foo" and "foo/bar" becomes "foo". + """ dir = os.path.dirname(text) if dir == "": return os.path.basename(text) @@ -234,12 +292,19 @@ return dir def tabindent(text): + """:tabindent: Any text. Returns the text, with every line except the + first starting with a tab character. + """ return indent(text, '\t') def urlescape(text): + """:urlescape: Any text. Escapes all "special" characters. For example, + "foo bar" becomes "foo%20bar". + """ return urllib.quote(text) def userfilter(text): + """:user: Any text. Returns the user portion of an email address.""" return util.shortuser(text) def xmlescape(text): @@ -286,3 +351,21 @@ "user": userfilter, "xmlescape": xmlescape, } + +def makedoc(topic, doc): + """Generate and include templatefilters help in templating topic.""" + entries = [] + for name in sorted(filters): + text = (filters[name].__doc__ or '').rstrip() + if not text: + continue + text = gettext(text) + lines = text.splitlines() + lines[1:] = [(' ' + l.strip()) for l in lines[1:]] + entries.append('\n'.join(lines)) + entries = '\n\n'.join(entries) + doc = doc.replace('.. filtersmarker', entries) + return doc + +# tell hggettext to extract docstrings from these functions: +i18nfunctions = filters.values()