def get_macro_description(self, name):
return cleandoc("""Shows a named icon that can be in line with text.
Syntax:
{{{
[[Icon(name, size)]]
}}}
where
* `name` is the name of the icon. When `name` contains a
pattern character (`*` or `?`), a 2-column preview of
matching icons is presented, which should mainly be used for
finding and selecting an icon during wiki page editing in
side-by-side mode (however, no more than %d icons are
presented to prevent exhaustive network traffic.)
* `size` is optionally one of `small`, `medium` or `large` or
an abbreviation thereof (defaults `small`).
Example:
{{{
[[Icon(smiley)]]
}}}
Use `ShowIcons` for static presentation of available icons.
Smileys like `:-)` are automatically rendered as icons. Use
`ShowSmileys` to se all available smileys.
Following wiki markup is equivalent to using this macro:
{{{
(|name, size|)
}}}
""" % self.icon_limit)
def get_macro_description(self, name):
return cleandoc("""Shows a named icon that can be in line with text.
Syntax:
{{{
[[Icon(name, size)]]
}}}
where
* `name` is the name of the icon. When `name` contains a
pattern character (`*` or `?`), a 2-column preview of
matching icons is presented, which should mainly be used for
finding and selecting an icon during wiki page editing in
side-by-side mode (however, no more than %d icons are
presented to prevent exhaustive network traffic.)
* `size` is optionally one of `small`, `medium` or `large` or
an abbreviation thereof (defaults `small`).
Example:
{{{
[[Icon(smiley)]]
}}}
Use `ShowIcons` for static presentation of available icons.
Smileys like `:-)` are automatically rendered as icons. Use
`ShowSmileys` to se all available smileys.
Following wiki markup is equivalent to using this macro:
{{{
(|name, size|)
}}}
""" % self.icon_limit)
def get_macro_description(self, name):
return cleandoc("""Renders in a table the list of available smileys.
Optional argument is the number of columns in the table
(defaults 3).
Comment: Prefixing a character sequence with `!` prevents it
from being interpreted as a smiley.
""")
def get_macro_description(self, name):
return cleandoc("""Renders in a table the list of available smileys.
Optional argument is the number of columns in the table
(defaults 3).
Comment: Prefixing a character sequence with `!` prevents it
from being interpreted as a smiley.
""")
def get_macro_description(self, name):
return cleandoc("""Renders in a table the list of known phrases that
are highlighted to catch attention.
Comment: Any delimiter `():<>` adjacent to a phrase will not be
presented. This makes it possible to naturally write `FIXME:`,
for example, but view the phrase highlighted without the colon
(`:`) which would not look natural. Prefixing a phrase with `!`
prevents it from being highlighted.
""")
def get_macro_description(self, name):
return cleandoc("""Renders in a table the list of known phrases that
are highlighted to catch attention.
Comment: Any delimiter `():<>` adjacent to a phrase will not be
presented. This makes it possible to naturally write `FIXME:`,
for example, but view the phrase highlighted without the colon
(`:`) which would not look natural. Prefixing a phrase with `!`
prevents it from being highlighted.
""")
def __init__(self, section, name, default=None, doc='',
doc_domain='tracini'):
"""Create the configuration option.
@param section: the name of the configuration section this option
belongs to
@param name: the name of the option
@param default: the default value for the option
@param doc: documentation of the option
"""
self.section = section
self.name = name
self.default = default
self.registry[(self.section, self.name)] = self
self.__doc__ = cleandoc(doc)
self.doc_domain = doc_domain
def __init__(self, section, name, default=None, doc='',
doc_domain='tracini'):
"""Create the configuration option.
@param section: the name of the configuration section this option
belongs to
@param name: the name of the option
@param default: the default value for the option
@param doc: documentation of the option
"""
self.section = section
self.name = name
self.default = default
self.registry[(self.section, self.name)] = self
self.__doc__ = cleandoc(doc)
self.doc_domain = doc_domain
def get_macro_description(self, name):
return cleandoc("""Decorate text with colors.
Syntax:
{{{
[[Color(text, fg/bg/size)]]
}}}
where
* `text` is the text to decorate. Enter a leading and/or
trailing space character to surround the text with a
decorated space.
* `fg/bg/size` defines the foreground and background colors,
and a font size. All parameters are optional and separated
by slash character (`/`).
Colors may be specified as an RGB triplet in hexadecimal format
(a hex triplet; e.g. `#000` or `#000000` for black); they may
also be specified according to their common English names (e.g.
red, green, blue etc.). See
[http://en.wikipedia.org/wiki/Web_colors here] for details.
Examples:
{{{
[[Color(Large red on yellow, red/yellow/150%)]]
[[Color(Red on yellow, red/yellow)]]
[[Color(Yellow background, /yellow)]]
[[Color(Large red, #f00/2em)]]
[[Color(Large on yellow, /yellow/20px)]]
[[Color(Text, can, have, commas, /yellow)]]
[[Color( Surrounding space is also decorated , white/red)]]
}}}
To set the foreground color for a larger block, the processor
variant can be used ''(background color and font size may not
display as expected due to the mechanisms of cascading style
sheets, be advised and use the ''color'' parameter only)'':
{{{
{{{#!Color color=green
...
}}}
}}}
""")
def get_macro_description(self, name):
return cleandoc("""
Display the list of available repositories.
Can be given the following named arguments:
''format''::
Select the rendering format:
- ''compact'' produces a comma-separated list of repository prefix
names (default)
- ''list'' produces a description list of repository prefix names
- ''table'' produces a table view, similar to the one visible in
the ''Browse View'' page
''glob''::
Do a glob-style filtering on the repository names (defaults to '*')
''order''::
Order repositories by the given column (one of "name", "date" or
"author")
''desc''::
When set to 1, order by descending order
(''since 0.12'')
""")
def get_macro_description(self, name):
return cleandoc("""
Display the list of available repositories.
Can be given the following named arguments:
''format''::
Select the rendering format:
- ''compact'' produces a comma-separated list of repository prefix
names (default)
- ''list'' produces a description list of repository prefix names
- ''table'' produces a table view, similar to the one visible in
the ''Browse View'' page
''glob''::
Do a glob-style filtering on the repository names (defaults to '*')
''order''::
Order repositories by the given column (one of "name", "date" or
"author")
''desc''::
When set to 1, order by descending order
(''since 0.12'')
""")
def get_macro_description(self, name):
#noinspection PyStringFormat
return cleandoc("""Renders in a table a list of available icons.
No more than %(showicons_limit)d icons are displayed to prevent
exhaustive network traffic.
Syntax:
{{{
[[ShowIcons(cols, name-pattern, size, header, limit)]]
}}}
where
* `cols` is optionally the number of columns in the table
(defaults 3).
* `name-pattern` selects which icons to list (use `*` and
`?`).
* `size` is optionally one of `small`, `medium` or `large` or
an abbreviation thereof (defaults `small`).
* `header` is optionally one of `header` and `noheader` or
an abbreviation thereof (header is displayed by default)
* `limit` specifies an optional upper limit of number of
displayed icons (however, no more than %(showicons_limit)d
will be displayed).
The last three optional parameters (`size`, `header` and
`limit`) can be stated in any order.
Example:
{{{
[[ShowIcons(smile*)]] # all small icons matching smile*
[[ShowIcons(4, smile*)]] # four columns
[[ShowIcons(smile*, 10)]] # limit to 10 icons
[[ShowIcons(smile*, 10, nohead)]] # no header
[[ShowIcons(smile*, m)]] # medium-size
}}}
""" % {'showicons_limit': self.showicons_limit})
def get_macro_description(self, name):
#noinspection PyStringFormat
return cleandoc("""Renders in a table a list of available icons.
No more than %(showicons_limit)d icons are displayed to prevent
exhaustive network traffic.
Syntax:
{{{
[[ShowIcons(cols, name-pattern, size, header, limit)]]
}}}
where
* `cols` is optionally the number of columns in the table
(defaults 3).
* `name-pattern` selects which icons to list (use `*` and
`?`).
* `size` is optionally one of `small`, `medium` or `large` or
an abbreviation thereof (defaults `small`).
* `header` is optionally one of `header` and `noheader` or
an abbreviation thereof (header is displayed by default)
* `limit` specifies an optional upper limit of number of
displayed icons (however, no more than %(showicons_limit)d
will be displayed).
The last three optional parameters (`size`, `header` and
`limit`) can be stated in any order.
Example:
{{{
[[ShowIcons(smile*)]] # all small icons matching smile*
[[ShowIcons(4, smile*)]] # four columns
[[ShowIcons(smile*, 10)]] # limit to 10 icons
[[ShowIcons(smile*, 10, nohead)]] # no header
[[ShowIcons(smile*, m)]] # medium-size
}}}
""" % {'showicons_limit': self.showicons_limit})
def get_macro_description(self, name):
if name == 'box':
return cleandoc("""\
View wiki text in a box.
Syntax:
{{{
{{{#!box type align=... width=...
wiki text
}}}
}}}
or preferably when content is short:
{{{
[[box(wiki text, type=..., align=..., width=...)]]
}}}
where
* `type` is an optional flag, or parameter, to call for
attention depending on type of matter. When `type` is set,
the box is decorated with an icon (except for `news`) and
colored, depending on what ''urgency'' the type represents:
%s
`type` may be abbreviated as long as the abbreviation is
unique for one of the keywords above.
* `align` is optionally one of `right`, `left` or `center`.
The `rbox` macro is an alias for `align=right`.
* `width` is optional and sets the width of the box (defaults
`auto` except for right aligned boxes which defaults a fixed
width). `width` should be set when `align=center` for
proper results.
Examples:
{{{
{{{#!box warn
= Warning
Beware of the bugs
}}}
[[box(Beware of the bugs, type=warn)]]
}}}
A `style` parameter is also accepted, to allow for custom
styling of the box. See also the `rbox`, `newsbox` and
`imagebox` macros (processors).
""") % self._get_type_description(' ' * 5)
elif name == 'rbox':
return cleandoc("""\
View a right-aligned box. (This is a shorthand for
`box align=right`)
Syntax:
{{{
{{{#!rbox type width=...
wiki text
}}}
}}}
or preferably when content is short:
{{{
[[rbox(wiki text, type=..., width=...)]]
}}}
where
* `type` is an optional flag, or parameter, to call for
attention depending on type of matter. When `type` is set,
the box is decorated with an icon (except for `news`) and
colored, depending on what ''urgency'' the type represents:
%s
`type` may be abbreviated as long as the abbreviation is
unique for one of the keywords above.
* `width` is optional and sets the width of the box (defaults
a fixed width). Use `width=auto` for an automatically sized
box.
Examples:
{{{
{{{#!rbox warn
= Warning
Beware of the bugs
}}}
[[rbox(Beware of the bugs, type=warn)]]
}}}
A `style` parameter is also accepted, to allow for custom
styling of the box. See also the `box`, `newsbox` and
`imagebox` macros (processors).
""") % self._get_type_description(' ' * 5)
elif name == 'newsbox':
return cleandoc("""\
Present a news box to the right. (This is a shorthand for
`rbox news`)
Syntax:
{{{
{{{#!newsbox
wiki text
}}}
}}}
The following parameters are also accepted:
* `width` -- Set the width of the box (defaults a fixed
width).
* `style` -- Custom styling of the box.
See also the `box`, `rbox` and `imagebox` macros (processors).
''(Comment: This box corresponds to the well-known
''`NewsFlash`'' macro.)''
""")
elif name == 'imagebox':
return cleandoc("""\
Present a centered box suitable for one image.
Syntax:
{{{
{{{#!imagebox
wiki text
}}}
}}}
This box is typically used together with the `Image` macro:
{{{
{{{#!imagebox
[[Image(file)]]
Caption
}}}
}}}
Note that the `size` parameter of the `Image` macro may not
behave as expected when using relative sizes (`%`).
The following parameters are also accepted:
* `align` -- One of `right`, `left` or `center` (defaults
`center`).
* `width` -- Set the width of the box (defaults `auto` except
for right aligned boxes which defaults a fixed width).
* `style` -- Custom styling of the box.
See also the `box`, `rbox` and `newsbox` macros (processors).
""")
def __init__(self, name, doc, doc_domain='tracini'):
"""Create the configuration section."""
self.name = name
self.registry[self.name] = self
self.__doc__ = cleandoc(doc)
self.doc_domain = doc_domain
def extract_python(fileobj, keywords, comment_tags, options):
"""Extract messages from Python source code, This is patched
extract_python from Babel to support keyword argument mapping.
`kwargs_maps` option: names of keyword arguments will be mapping to
index of messages array.
`cleandoc_keywords` option: a list of keywords to clean up the
extracted messages with `cleandoc`.
"""
from trac.util.compat import cleandoc
funcname = lineno = message_lineno = None
kwargs_maps = func_kwargs_map = None
call_stack = -1
buf = []
messages = []
messages_kwargs = {}
translator_comments = []
in_def = in_translator_comments = False
comment_tag = None
encoding = str(
parse_encoding(fileobj) or options.get('encoding', 'iso-8859-1'))
kwargs_maps = _DEFAULT_KWARGS_MAPS.copy()
if 'kwargs_maps' in options:
kwargs_maps.update(options['kwargs_maps'])
cleandoc_keywords = set(_DEFAULT_CLEANDOC_KEYWORDS)
if 'cleandoc_keywords' in options:
cleandoc_keywords.update(options['cleandoc_keywords'])
tokens = generate_tokens(fileobj.readline)
tok = value = None
for _ in tokens:
prev_tok, prev_value = tok, value
tok, value, (lineno, _), _, _ = _
if call_stack == -1 and tok == NAME and value in ('def', 'class'):
in_def = True
elif tok == OP and value == '(':
if in_def:
# Avoid false positives for declarations such as:
# def gettext(arg='message'):
in_def = False
continue
if funcname:
message_lineno = lineno
call_stack += 1
kwarg_name = None
elif in_def and tok == OP and value == ':':
# End of a class definition without parens
in_def = False
continue
elif call_stack == -1 and tok == COMMENT:
# Strip the comment token from the line
value = value.decode(encoding)[1:].strip()
if in_translator_comments and \
translator_comments[-1][0] == lineno - 1:
# We're already inside a translator comment, continue
# appending
translator_comments.append((lineno, value))
continue
# If execution reaches this point, let's see if comment line
# starts with one of the comment tags
for comment_tag in comment_tags:
if value.startswith(comment_tag):
in_translator_comments = True
translator_comments.append((lineno, value))
break
elif funcname and call_stack == 0:
if tok == OP and value == ')':
if buf:
message = ''.join(buf)
if kwarg_name in func_kwargs_map:
messages_kwargs[kwarg_name] = message
else:
messages.append(message)
del buf[:]
else:
messages.append(None)
for name, message in messages_kwargs.iteritems():
if name not in func_kwargs_map:
continue
index = func_kwargs_map[name]
while index >= len(messages):
messages.append(None)
messages[index - 1] = message
if funcname in cleandoc_keywords:
messages = [m and cleandoc(m) for m in messages]
if len(messages) > 1:
messages = tuple(messages)
else:
messages = messages[0]
# Comments don't apply unless they immediately preceed the
# message
if translator_comments and \
translator_comments[-1][0] < message_lineno - 1:
translator_comments = []
yield (message_lineno, funcname, messages,
[comment[1] for comment in translator_comments])
funcname = lineno = message_lineno = None
kwarg_name = func_kwargs_map = None
call_stack = -1
messages = []
messages_kwargs = {}
translator_comments = []
in_translator_comments = False
elif tok == STRING:
# Unwrap quotes in a safe manner, maintaining the string's
# encoding
# https://sourceforge.net/tracker/?func=detail&atid=355470&
# aid=617979&group_id=5470
value = eval('# coding=%s\n%s' % (encoding, value),
{'__builtins__': {}}, {})
if isinstance(value, str):
value = value.decode(encoding)
buf.append(value)
elif tok == OP and value == '=' and prev_tok == NAME:
kwarg_name = prev_value
elif tok == OP and value == ',':
if buf:
message = ''.join(buf)
if kwarg_name in func_kwargs_map:
messages_kwargs[kwarg_name] = message
else:
messages.append(message)
del buf[:]
else:
messages.append(None)
kwarg_name = None
if translator_comments:
# We have translator comments, and since we're on a
# comma(,) user is allowed to break into a new line
# Let's increase the last comment's lineno in order
# for the comment to still be a valid one
old_lineno, old_comment = translator_comments.pop()
translator_comments.append(
(old_lineno + 1, old_comment))
elif call_stack > 0 and tok == OP and value == ')':
call_stack -= 1
elif funcname and call_stack == -1:
funcname = func_kwargs_map = kwarg_name = None
elif tok == NAME and value in keywords:
funcname = value
func_kwargs_map = kwargs_maps.get(funcname, {})
kwarg_name = None
def __init__(self, name, doc, doc_domain='tracini'):
"""Create the configuration section."""
self.name = name
self.registry[self.name] = self
self.__doc__ = cleandoc(doc)
self.doc_domain = doc_domain
def extract_python(fileobj, keywords, comment_tags, options):
"""Extract messages from Python source code, This is patched
extract_python from Babel to support keyword argument mapping.
`kwargs_maps` option: names of keyword arguments will be mapping to
index of messages array.
`cleandoc_keywords` option: a list of keywords to clean up the
extracted messages with `cleandoc`.
"""
from trac.util.compat import cleandoc
funcname = lineno = message_lineno = None
kwargs_maps = func_kwargs_map = None
call_stack = -1
buf = []
messages = []
messages_kwargs = {}
translator_comments = []
in_def = in_translator_comments = False
comment_tag = None
encoding = parse_encoding(fileobj) \
or options.get('encoding', 'iso-8859-1')
kwargs_maps = _DEFAULT_KWARGS_MAPS.copy()
if 'kwargs_maps' in options:
kwargs_maps.update(options['kwargs_maps'])
cleandoc_keywords = set(_DEFAULT_CLEANDOC_KEYWORDS)
if 'cleandoc_keywords' in options:
cleandoc_keywords.update(options['cleandoc_keywords'])
tokens = generate_tokens(fileobj.readline)
tok = value = None
for _ in tokens:
prev_tok, prev_value = tok, value
tok, value, (lineno, _), _, _ = _
if call_stack == -1 and tok == NAME and value in ('def', 'class'):
in_def = True
elif tok == OP and value == '(':
if in_def:
# Avoid false positives for declarations such as:
# def gettext(arg='message'):
in_def = False
continue
if funcname:
message_lineno = lineno
call_stack += 1
kwarg_name = None
elif in_def and tok == OP and value == ':':
# End of a class definition without parens
in_def = False
continue
elif call_stack == -1 and tok == COMMENT:
# Strip the comment token from the line
value = value.decode(encoding)[1:].strip()
if in_translator_comments and \
translator_comments[-1][0] == lineno - 1:
# We're already inside a translator comment, continue
# appending
translator_comments.append((lineno, value))
continue
# If execution reaches this point, let's see if comment line
# starts with one of the comment tags
for comment_tag in comment_tags:
if value.startswith(comment_tag):
in_translator_comments = True
translator_comments.append((lineno, value))
break
elif funcname and call_stack == 0:
if tok == OP and value == ')':
if buf:
message = ''.join(buf)
if kwarg_name in func_kwargs_map:
messages_kwargs[kwarg_name] = message
else:
messages.append(message)
del buf[:]
else:
messages.append(None)
for name, message in messages_kwargs.iteritems():
if name not in func_kwargs_map:
continue
index = func_kwargs_map[name]
while index >= len(messages):
messages.append(None)
messages[index - 1] = message
if funcname in cleandoc_keywords:
messages = [m and cleandoc(m) for m in messages]
if len(messages) > 1:
messages = tuple(messages)
else:
messages = messages[0]
# Comments don't apply unless they immediately preceed the
# message
if translator_comments and \
translator_comments[-1][0] < message_lineno - 1:
translator_comments = []
yield (message_lineno, funcname, messages,
[comment[1] for comment in translator_comments])
funcname = lineno = message_lineno = None
kwarg_name = func_kwargs_map = None
call_stack = -1
messages = []
messages_kwargs = {}
translator_comments = []
in_translator_comments = False
elif tok == STRING:
# Unwrap quotes in a safe manner, maintaining the string's
# encoding
# https://sourceforge.net/tracker/?func=detail&atid=355470&
# aid=617979&group_id=5470
value = eval('# coding=%s\n%s' % (encoding, value),
{'__builtins__':{}}, {})
if isinstance(value, str):
value = value.decode(encoding)
buf.append(value)
elif tok == OP and value == '=' and prev_tok == NAME:
kwarg_name = prev_value
elif tok == OP and value == ',':
if buf:
message = ''.join(buf)
if kwarg_name in func_kwargs_map:
messages_kwargs[kwarg_name] = message
else:
messages.append(message)
del buf[:]
else:
messages.append(None)
kwarg_name = None
if translator_comments:
# We have translator comments, and since we're on a
# comma(,) user is allowed to break into a new line
# Let's increase the last comment's lineno in order
# for the comment to still be a valid one
old_lineno, old_comment = translator_comments.pop()
translator_comments.append((old_lineno+1, old_comment))
elif call_stack > 0 and tok == OP and value == ')':
call_stack -= 1
elif funcname and call_stack == -1:
funcname = func_kwargs_map = kwarg_name = None
elif tok == NAME and value in keywords:
funcname = value
func_kwargs_map = kwargs_maps.get(funcname, {})
kwarg_name = None
def get_macro_description(self, name):
if name == 'box':
return cleandoc("""\
View wiki text in a box.
Syntax:
{{{
{{{#!box type align=... width=...
wiki text
}}}
}}}
or preferably when content is short:
{{{
[[box(wiki text, type=..., align=..., width=...)]]
}}}
where
* `type` is an optional flag, or parameter, to call for
attention depending on type of matter. When `type` is set,
the box is decorated with an icon (except for `news`) and
colored, depending on what ''urgency'' the type represents:
%s
`type` may be abbreviated as long as the abbreviation is
unique for one of the keywords above.
* `align` is optionally one of `right`, `left` or `center`.
The `rbox` macro is an alias for `align=right`.
* `width` is optional and sets the width of the box (defaults
`auto` except for right aligned boxes which defaults a fixed
width). `width` should be set when `align=center` for
proper results.
Examples:
{{{
{{{#!box warn
= Warning
Beware of the bugs
}}}
[[box(Beware of the bugs, type=warn)]]
}}}
A `style` parameter is also accepted, to allow for custom
styling of the box. See also the `rbox`, `newsbox` and
`imagebox` macros (processors).
""") % self._get_type_description(' ' * 5)
elif name in ('rbox', 'lbox'):
return cleandoc("""\
View a %(direction)s-aligned box. (This is a shorthand for
`box align=%(direction)s`)
Syntax:
{{{
{{{#!%(name)s type width=...
wiki text
}}}
}}}
or preferably when content is short:
{{{
[[%(name)s(wiki text, type=..., width=...)]]
}}}
where
* `type` is an optional flag, or parameter, to call for
attention depending on type of matter. When `type` is set,
the box is decorated with an icon (except for `news`) and
colored, depending on what ''urgency'' the type represents:
%(type_description)s
`type` may be abbreviated as long as the abbreviation is
unique for one of the keywords above.
* `width` is optional and sets the width of the box (defaults
a fixed width). Use `width=auto` for an automatically sized
box.
Examples:
{{{
{{{#!%(name)s warn
= Warning
Beware of the bugs
}}}
[[%(name)s(Beware of the bugs, type=warn)]]
}}}
A `style` parameter is also accepted, to allow for custom
styling of the box. See also the `box`, `newsbox` and
`imagebox` macros (processors).
""") % {
'name': name,
'direction': 'right' if name is 'rbox' else 'left',
'type_description': self._get_type_description(' ' * 5),
}
elif name == 'newsbox':
return cleandoc("""\
Present a news box to the right. (This is a shorthand for
`rbox news`)
Syntax:
{{{
{{{#!newsbox
wiki text
}}}
}}}
The following parameters are also accepted:
* `width` -- Set the width of the box (defaults a fixed
width).
* `style` -- Custom styling of the box.
See also the `box`, `rbox` and `imagebox` macros (processors).
''(Comment: This box corresponds to the well-known
''`NewsFlash`'' macro.)''
""")
elif name == 'imagebox':
return cleandoc("""\
Present a centered box suitable for one image.
Syntax:
{{{
{{{#!imagebox
wiki text
}}}
}}}
This box is typically used together with the `Image` macro:
{{{
{{{#!imagebox
[[Image(file)]]
Caption
}}}
}}}
Note that the `size` parameter of the `Image` macro may not
behave as expected when using relative sizes (`%`).
The following parameters are also accepted:
* `align` -- One of `right`, `left` or `center` (defaults
`center`).
* `width` -- Set the width of the box (defaults `auto` except
for right aligned boxes which defaults a fixed width).
* `style` -- Custom styling of the box.
See also the `box`, `rbox` and `newsbox` macros (processors).
""")
