Trac Macros

  1. Trac Macros
    1. Using Macros
      1. Example
    2. Available Macros
    3. Macros from around the world
    4. Developing Custom Macros
    5. Implementation
      1. Macro without arguments
      2. Macro with arguments
      3. expand_macro details

Trac macros are plugins to extend the Trac engine with custom 'functions' written in Python. A macro inserts dynamic HTML data in any context supporting WikiFormatting.

Another kind of macros are WikiProcessors. They typically deal with alternate markup formats and representation of larger blocks of information (like source code highlighting).

Using Macros

Macro calls are enclosed in two square brackets. Like Python functions, macros can also have arguments, a comma separated list within parentheses.

Trac macros can also be written as TracPlugins. This gives them some capabilities that macros do not have, such as being able to directly access the HTTP request.

Example

A list of 3 most recently changed wiki pages starting with 'Trac': 

 [[RecentChanges(Trac,3)]]

Display:

07/12/08

Available Macros

Note that the following list will only contain the macro documentation if you've not enabled -OO optimizations, or not set the PythonOptimize option for mod_python.

[[InterTrac]]

Provide a list of known InterTrac prefixes.

[[TitleIndex]]

Inserts an alphabetic list of all wiki pages into the output.

Accepts a prefix string as parameter: if provided, only pages with names that start with the prefix are included in the resulting list. If this parameter is omitted, all pages are listed.

Alternate format and depth can be specified:

  • format=group: The list of page will be structured in groups according to common prefix. This format also supports a min=n argument, where n is the minimal number of pages for a group.
  • depth=n: limit the depth of the pages to list. If set to 0, only toplevel pages will be shown, if set to 1, only immediate children pages will be shown, etc. If not set, or set to -1, all pages in the hierarchy will be shown.
[[RecentChanges]]

Lists all pages that have recently been modified, grouping them by the day they were last modified.

This macro accepts two parameters. The first is a prefix string: if provided, only pages with names that start with the prefix are included in the resulting list. If this parameter is omitted, all pages are listed.

The second parameter is a number for limiting the number of pages returned. For example, specifying a limit of 5 will result in only the five most recently changed pages to be included in the list.

[[PageOutline]]

Displays a structural outline of the current wiki page, each item in the outline being a link to the corresponding heading.

This macro accepts three optional parameters:

  • The first is a number or range that allows configuring the minimum and maximum level of headings that should be included in the outline. For example, specifying "1" here will result in only the top-level headings being included in the outline. Specifying "2-3" will make the outline include all headings of level 2 and 3, as a nested list. The default is to include all heading levels.
  • The second parameter can be used to specify a custom title (the default is no title).
  • The third parameter selects the style of the outline. This can be either inline or pullout (the latter being the default). The inline style renders the outline as normal part of the content, while pullout causes the outline to be rendered in a box that is by default floated to the right side of the other content.
[[Image]]

Embed an image in wiki-formatted text.

The first argument is the file specification. The file specification may reference attachments in three ways:

  • module:id:file, where module can be either wiki or ticket, to refer to the attachment named file of the specified wiki page or ticket.
  • id:file: same as above, but id is either a ticket shorthand or a Wiki page name.
  • file to refer to a local attachment named 'file'. This only works from within that wiki page or a ticket.

Also, the file specification may refer to repository files, using the source:file syntax (source:file@rev works also).

Files can also be accessed with a direct URLs; /file for a project-relative, //file for a server-relative, or http://server/file for absolute location of the file.

The remaining arguments are optional and allow configuring the attributes and style of the rendered <img> element:

  • digits and unit are interpreted as the size (ex. 120, 25%) for the image
  • right, left, top or bottom are interpreted as the alignment for the image
  • link=some TracLinks... replaces the link to the image source by the one specified using a TracLinks. If no value is specified, the link is simply removed.
  • nolink means without link to image source (deprecated, use link=)
  • key=value style are interpreted as HTML attributes or CSS style indications for the image. Valid keys are:
    • align, border, width, height, alt, title, longdesc, class, id and usemap
    • border can only be a number

Examples: 

    [[Image(photo.jpg)]]                           # simplest
    [[Image(photo.jpg, 120px)]]                    # with image width size
    [[Image(photo.jpg, right)]]                    # aligned by keyword
    [[Image(photo.jpg, nolink)]]                   # without link to source
    [[Image(photo.jpg, align=right)]]              # aligned by attribute

You can use image from other page, other ticket or other module. 

    [[Image(OtherPage:foo.bmp)]]    # if current module is wiki
    [[Image(base/sub:bar.bmp)]]     # from hierarchical wiki page
    [[Image(#3:baz.bmp)]]           # if in a ticket, point to #3
    [[Image(ticket:36:boo.jpg)]]
    [[Image(source:/images/bee.jpg)]] # straight from the repository!
    [[Image(htdocs:foo/bar.png)]]   # image file in project htdocs dir.

Adapted from the Image.py macro created by Shun-ichi Goto <gotoh@…>

[[MacroList]]

Displays a list of all installed Wiki macros, including documentation if available.

Optionally, the name of a specific macro can be provided as an argument. In that case, only the documentation for that macro will be rendered.

Note that this macro will not be able to display the documentation of macros if the PythonOptimize option is enabled for mod_python!

[[TracIni]]

Produce documentation for Trac configuration file.

Typically, this will be used in the TracIni page. Optional arguments are a configuration section filter, and a configuration option name filter: only the configuration options whose section and name start with the filters are output.

[[TracGuideToc]]

This macro shows a quick and dirty way to make a table-of-contents for a set of wiki pages.

[[TicketQuery]]

Macro that lists tickets that match certain criteria.

This macro accepts a comma-separated list of keyed parameters, in the form "key=value".

If the key is the name of a field, the value must use the syntax of a filter specifier as defined in TracQuery#QueryLanguage. Note that this is not the same as the simplified URL syntax used for query: links starting with a ? character.

In addition to filters, several other named parameters can be used to control how the results are presented. All of them are optional.

The format parameter determines how the list of tickets is presented:

  • list -- the default presentation is to list the ticket ID next to the summary, with each ticket on a separate line.
  • compact -- the tickets are presented as a comma-separated list of ticket IDs.
  • count -- only the count of matching tickets is displayed
  • table -- a view similar to the custom query view (but without the controls)

The max parameter can be used to limit the number of tickets shown (defaults to 0, i.e. no maximum).

The order parameter sets the field used for ordering tickets (defaults to id).

The desc parameter indicates whether the order of the tickets should be reversed (defaults to false).

The group parameter sets the field used for grouping tickets (defaults to not being set).

The groupdesc parameter indicates whether the natural display order of the groups should be reversed (defaults to false).

The verbose parameter can be set to a true value in order to get the description for the listed tickets. For table format only. deprecated in favor of the rows parameter

The rows parameter can be used to specify which field(s) should be viewed as a row, e.g. rows=description|summary

For compatibility with Trac 0.10, if there's a second positional parameter given to the macro, it will be used to specify the format. Also, using "&" as a field separator still works (except for order) but is deprecated.

[[InterWiki]]

Provide a description list for the known InterWiki prefixes.

[[TracAdminHelp]]

Displays help for trac-admin commands.

Examples: 

[[TracAdminHelp]]               # all commands
[[TracAdminHelp(wiki)]]         # all wiki commands
[[TracAdminHelp(wiki export)]]  # the "wiki export" command
[[TracAdminHelp(upgrade)]]      # the upgrade command
[[IncludeRegressedRevisionNumber]]

[[IncludeLongTimeRegressions]]

[[RegressionResults]]

Display regression results. Example: {{.{

Regression results for r2470

2470 2469 2467 2466 2463 2461 2460 2456 2454 2452 2449 2446 2445 2444 2442
2440 2435 2433 2432 2431 2429 2430 2428 2426 2424 2418 2417 2414 2413 2412
2411 2410 2407 2401 2398 2396 2395 2394 2393 2392 2391 2388 2387 2380 2386
2385 2384 2383 2382 2381 2379 2376 2375 2374 2373 2372 2371 2369 2367 2364
2363 2359 2357 2351 2348 2340 2334 2333 2331 2330 2324 2323 2320 2314 2313
2295 2294 2291 2288 2278 
Sat Apr 24 19:20:38 2010: cd regression; ./regress.pike
reading:235     FAIL 2 C1 [1 C1]
reading                                  1.37    101557       0        0
owl:123         PASS 1 C5 [1 C5]
owl                                     40.08  15010856   19015    92888
ld_owl                                  19.53   4773660   22556     5653
optics                                   1.26    259864       0     2689
filllib                                  6.17   1225763    1567     9777
atari_atari                              8.90   3301273    2517    18967
connection                               8.03   3630849       0    41483
break_in                                 0.84    449440     465     4528
blunder                                 10.99   3727917    3523    17784
unconditional                            1.65     38618       0        0
trevora:290     FAIL C8 [!C8]
trevora:530     FAIL F2 [H4]
trevora                                 32.13  14726317   52826    81035
nngs1                                  108.66  49953154   69137   386437
strategy                                89.61  35309939   71303   269992
endgame:1010    FAIL A8 [A7]
endgame                                 21.04   6747358    2752    66695
heikki                                   1.76    882129    1334     5923
neurogo                                 83.26  27432937   62973   157191
arb                                     11.89   4191260    4625    21789
rosebud                                  3.40   1184040    3580     8612
golife:1        PASS C7 [C7]
golife                                   7.06   2696990   10313     8160
arion                                   11.70   5113626    5474    26792
viking                                  27.28  11734119   16373    98400
ego                                     13.72   6176236    5134    57184
dniwog                                  21.51   7593913   19271    37793
lazarus:7       FAIL L12 [T5]
lazarus                                 85.06  23348643   72970    98725
trevorb:590     PASS M9 [H12|M9]
trevorb                                 58.11  26208008   35646   229450
strategy2:73    PASS R17 [F7|R17|P15]
strategy2                              107.49  38621808   85279   281990
nicklas1                                61.33  21562701   47800   137566
nicklas2:902    PASS critical PASS PASS [critical (.*) (.*)]
nicklas2                                 9.80   3803198   13007    11829
nicklas3                                 1.82    611683    3342      503
nicklas4                                14.24   5155241   10434    39157
nicklas5                                26.74   9358442   20651    55150
manyfaces                               22.51  10173906   18513    83994
niki                                    37.33  13983992   23003   122080
trevor:261      FAIL A2 [F9]
trevor                                  39.59  15903630   41063    90768
tactics                                 12.35   4860471    6088    39426
buzco                                   19.84   8175481   16474    40441
nngs:240        FAIL T6 [R4|S4|Q2]
nngs:820        FAIL D14 [J13|L9]
nngs                                   268.86 110656627  185968   764237
trevorc:240     FAIL K3 [K2]
trevorc:820     PASS A6 [A6]
trevorc                                103.30  47071650   74652   434990
strategy3                               81.97  27595533   58512   244551
capture                                  0.17     17540       0        0
connect                                  1.10    286534       0     3689
global                                  93.83  34336877   74750   214320
vie                                     12.37   4240783    4775    29118
arend                                   67.58  32873239   25304   335985
13x13                                  107.33  43663485  122985   350412
semeai:47       FAIL 1 1 T11 [1 0 (PASS|T11|T9|R9|T10|R10|R11)]
semeai:107      PASS D6 [D6|C7]
semeai:120      FAIL 1 0 A14 [0 0 PASS]
semeai:133      FAIL 1 2 H2 [1 1 H2]
semeai:134      PASS 1 1 H2 [1 1 H2]
semeai:151      FAIL alive [dead]
semeai:152      FAIL dead [alive]
semeai                                  29.61   7721602   21096    39696
STS-RV_0:1      FAIL 1 1 F9 [1 1 (PASS|A9|C9)]
STS-RV_0                                 0.64     52912     260       42
STS-RV_1:3      PASS 1 1 D8 [1 1 (D8|C3|B3|A3)]
STS-RV_1:5      PASS 1 1 M4 [1 1 (M4|N4|R3|R2|R1)]
STS-RV_1:20     PASS 1 1 S2 [1 1 (R3|S4|S2|T3)]
STS-RV_1:31     PASS 1 0 C2 [1 0 (PASS|C1|C2)]
STS-RV_1:54     PASS 1 0 O2 [1 0 (O2|O1|R2|Q1|S1)]
STS-RV_1:56     PASS 1 0 H15 [1 0 (J15|H15|F14|E13|E12|F10)]
STS-RV_1:59     PASS 0 0 PASS [0 0 PASS]
STS-RV_1:63     PASS 1 0 PASS [1 0 (PASS|S17|T16)]
STS-RV_1:64     PASS 1 0 M15 [1 0 (PASS|M15|N15|O15)]
STS-RV_1:65     PASS 1 0 G7 [1 0 (PASS|G7|J5|K4|L4|M5|N6|N7)]
STS-RV_1:68     PASS 1 0 K19 [1 0 (G15|H15|K19|K18|G17|G19|F18|H18)]
STS-RV_1:70     PASS 1 0 C3 [1 0 (C3|B4)]
STS-RV_1:73     PASS 1 0 T15 [1 0 (PASS|M11|N10|O10|S14|T15)]
STS-RV_1:74     PASS 1 0 M19 [1 0 (PASS|M18|M19)]
STS-RV_1:75     PASS 1 1 C18 [1 1 (C18|B17|D17)]
STS-RV_1:79     PASS 1 1 E19 [1 1 (E19|F18|F17)]
STS-RV_1:80     PASS 1 0 F12 [1 0 (F12|F11|F10|F9|E8|D8)]
STS-RV_1:81     PASS 1 1 E1 [1 1 E1]
STS-RV_1:82     PASS 1 0 B2 [1 0 B2]
STS-RV_1:83     PASS 1 0 O7 [1 0 (PASS|M5|N5|O6|O7)]
STS-RV_1:84     PASS 1 0 R8 [1 0 (PASS|R8|S8|T8)]
STS-RV_1:85     PASS 1 1 L16 [1 1 (N17|L16)]
STS-RV_1:86     PASS 1 1 R16 [1 1 (Q17|R16)]
STS-RV_1:87     PASS 1 1 D17 [1 1 (B17|D17)]
STS-RV_1:89     PASS 1 1 S6 [1 1 (T5|S6)]
STS-RV_1:95     PASS 1 1 D17 [1 1 (PASS|B17|D17)]
STS-RV_1:96     PASS 0 0 PASS [0 0 PASS]
STS-RV_1:97     PASS 1 1 S6 [1 1 (PASS|S6|T5)]
STS-RV_1:98     PASS 0 0 PASS [0 0 PASS]
STS-RV_1:119    PASS 1 1 C2 [1 1 C2]
STS-RV_1:139    PASS 1 1 T17 [1 1 (PASS|T17|T18)]
STS-RV_1:140    PASS 0 0 PASS [0 0 PASS]
STS-RV_1:158    PASS 1 1 P6 [1 1 (N3|O5|P6|Q6|R6|S6|T6)]
STS-RV_1:163    PASS 1 1 C18 [1 1 (C18|D17)]
STS-RV_1:164    PASS 1 0 C18 [1 0 C18]
STS-RV_1:166    PASS 1 1 D2 [1 1 D2]
STS-RV_1:168    PASS 1 1 S11 [1 1 (T10|R10|S11)]
STS-RV_1:169    PASS 1 1 K18 [1 1 K18]
STS-RV_1:173    PASS 1 1 D17 [1 1 D17]
STS-RV_1:175    PASS 1 1 H2 [1 1 H2]
STS-RV_1:179    PASS 1 0 Q17 [1 0 Q17]
STS-RV_1:184    PASS 1 1 C11 [1 1 C11]
STS-RV_1:186    PASS 1 1 J2 [1 1 (J2|B2|B3|D3)]
STS-RV_1:187    PASS 1 1 R4 [1 1 R4]
STS-RV_1:188    PASS 1 0 R4 [1 0 R4]
STS-RV_1:189    PASS 1 1 L18 [1 1 L18]
STS-RV_1:190    PASS 1 0 L18 [1 0 L18]
STS-RV_1:194    PASS 1 0 B17 [1 0 (PASS|B17)]
STS-RV_1:195    PASS 1 1 K2 [1 1 K2]
STS-RV_1:196    PASS 1 1 D3 [1 1 D3]
STS-RV_1:197    PASS 1 1 T1 [1 1 (T4|S3|T1)]
STS-RV_1:205    PASS 1 1 C2 [1 1 C2]
STS-RV_1                                 8.27    247054    5552      262
STS-RV_e:2      PASS 1 1 B17 [1 1 B17]
STS-RV_e:13     PASS 1 0 PASS [1 0 PASS]
STS-RV_e:14     PASS 1 0 PASS [1 0 PASS]
STS-RV_e:25     PASS 1 0 PASS [1 0 PASS]
STS-RV_e:26     PASS 1 0 PASS [1 0 PASS]
STS-RV_e:52     PASS 1 0 A15 [1 0 (PASS|A15)]
STS-RV_e:55     PASS 1 0 PASS [1 0 PASS]
STS-RV_e:56     PASS 1 0 PASS [1 0 PASS]
STS-RV_e:61     PASS 1 0 PASS [1 0 PASS]
STS-RV_e:62     PASS 1 0 PASS [1 0 PASS]
STS-RV_e:76     PASS 1 0 B18 [1 0 (PASS|D19|B18|A17)]
STS-RV_e:83     PASS 1 0 PASS [1 0 PASS]
STS-RV_e:84     PASS 1 0 PASS [1 0 PASS]
STS-RV_e:87     PASS 1 0 PASS [1 0 PASS]
STS-RV_e:88     PASS 1 0 PASS [1 0 PASS]
STS-RV_e:91     PASS 1 0 A6 [1 0 (C5|A6|C4)]
STS-RV_e:92     PASS 1 1 C5 [1 1 C5]
STS-RV_e:93     PASS 1 0 A18 [1 0 (B16|A18|D17)]
STS-RV_e:94     PASS 1 2 B16 [1 2 B16]
STS-RV_e:96     PASS 1 2 Q12 [1 2 Q12]
STS-RV_e:99     PASS 3 0 J17 [3 0 J17]
STS-RV_e:102    PASS 1 0 PASS [1 0 PASS]
STS-RV_e:110    PASS 1 2 C5 [1 2 C5]
STS-RV_e:157    PASS 1 0 PASS [1 0 PASS]
STS-RV_e:158    PASS 1 0 PASS [1 0 PASS]
STS-RV_e:183    PASS 2 2 R6 [2 2 (P1|Q5|R6|S6|T6)]
STS-RV_e:201    PASS 1 0 M1 [1 0 (L2|M1)]
STS-RV_e:225    PASS 1 0 B9 [1 0 B9]
STS-RV_e:226    PASS 1 1 C12 [1 1 (C12|C13)]
STS-RV_e:227    PASS 1 0 N2 [1 0 (P1|N2)]
STS-RV_e:229    PASS 1 0 T14 [1 0 T14]
STS-RV_e:230    PASS 1 1 T14 [1 1 T14]
STS-RV_e:231    PASS 1 0 H18 [1 0 H18]
STS-RV_e:232    PASS 1 1 H18 [1 1 H18]
STS-RV_e                                 3.10    154152     983      634
STS-RV_Misc:4   PASS 1 1 A10 [1 1 A10]
STS-RV_Misc:14  PASS 1 0 B9 [1 0 B9]
STS-RV_Misc:46  FAIL 0 0 PASS [1 1 D19]
STS-RV_Misc                              5.33    810589    4445     5205
trevord:680     PASS S16 [S16]
trevord                                135.99  62417235   46645   664170
strategy4:166   PASS D11 [D11]
strategy4                              155.41  62196431  111100   522146
owl1:279        PASS 1 PASS [1 PASS]
owl1:319        PASS 1 S6 [1 S6]
owl1:322        FAIL 1 D1 [0]
owl1:356        PASS 1 L3 [1 L3]
owl1:372        FAIL 0 [1 D18]
owl1:388        PASS 1 A2 [1 A2]
owl1:397        FAIL 1 [0]
owl1                                    30.14  12196041    9921   119591
handtalk                                53.67  22226052   33803   196229
nngs2:150       FAIL J18 [M3|L3]
nngs2:600       PASS B5 [B5]
nngs2                                  139.90  50691620  101229   301706
nngs3:260       PASS G12 [G12|G11]
nngs3                                  356.80 129202686  277755   922737
nngs4:170       PASS S6 [S6]
nngs4:200       FAIL S5 [T6]
nngs4:230       PASS Q18 [Q18]
nngs4:900       PASS Q9 [!Q18]
nngs4                                  293.35 106998486  240317   740357
strategy5:225   FAIL L11 [O12]
strategy5                               78.80  32081556   65076   215618
century2002                             58.55  21389042   53280   149208
auto01                                   2.58   1077266     794    10222
auto02                                   5.14   2181831    2939    23739
auto03                                   3.23   1710903     599    18060
auto04                                   1.65    779869     456     7124
auto_handtalk:3 FAIL 1 T15 [2 T15]
auto_handtalk                            4.78   1826365    2242    22097
safety                                   4.99   1986122    4224    24402
ninestones:570  FAIL A2 [A9|B10|D11|F11|J15|A16]
ninestones:760  FAIL J11 [J10]
ninestones                             256.08  84555969  195206   535944
tactics1                                 9.00   3292771    4634    36078
manyfaces1                              32.27  13276100   26794   108425
gunnar:101      PASS T8 [T8]
gunnar                                 176.39  66777035   92249   524860
arend2:10       PASS G3 [G3|F4]
arend2:210      FAIL N3 [K2]
arend2                                  66.55  26938887   51069   206963
nando:12        PASS 0 [0]
nando                                   26.68  10731603   12407   105471
thrash:26       PASS A1 [E1|A1]
thrash:27       PASS G3 [J6|G3|H2]
thrash:28       PASS G3 [A2|G3|H2]
thrash:29       PASS G3 [D3|G3|H2]
thrash                                  27.96   9676325   15720    67838
13x13b:21       FAIL J13 [K11]
13x13b                                  53.82  20618342   55092   147750
joseki                                  14.03   6615173   11105    31107
gifu03                                  95.75  41014550   53032   388533
seki:103        PASS B1 [B1|A2]
seki:112        PASS B1 [B1]
seki                                     5.86    410589    8610     4667
9x9:197         FAIL D8 [E8|H5]
9x9:250         PASS A2 [A2|C1|C2]
9x9:690         FAIL E9 [H1|J4]
9x9:700         FAIL A5 [B9]
9x9                                     96.99  40414618  164286   146800
cgf2004                                 24.68  11745142    9327   111637
kgs:300         PASS H4 [H4]
kgs                                    216.42  85629318  156910   614634
olympiad2004                            86.02  33805042   61423   227672
tiny                                     2.59    452794    6547      106
gifu05                                  27.02  10274720   13325    66608
13x13c                                  21.73   8584620   21494    29463
Total nodes: 1681532699 3257900 12365954
Total time: 4376.33 (4714.55)
Total uncertainty: 50.78
118 PASS
30 FAIL
}}.}

[[goban]]

[[tst]]

Macros from around the world

The  Trac Hacks site provides a wide collection of macros and other Trac plugins contributed by the Trac community. If you're looking for new macros, or have written one that you'd like to share with the world, please don't hesitate to visit that site.

Developing Custom Macros

Macros, like Trac itself, are written in the  Python programming language.

For more information about developing macros, see the development resources? on the main project site.

Implementation

Here are 2 simple examples on how to create a Macro with Trac 0.11? have a look at source:trunk/sample-plugins/Timestamp.py for an example that shows the difference between old style and new style macros and also source:trunk/wiki-macros/README which provides a little more insight about the transition.

Macro without arguments

It should be saved as TimeStamp.py as Trac will use the module name as the Macro name 

from datetime import datetime
# Note: since Trac 0.11, datetime objects are used internally

from genshi.builder import tag

from trac.util.datefmt import format_datetime, utc
from trac.wiki.macros import WikiMacroBase

class TimestampMacro(WikiMacroBase):
    """Inserts the current time (in seconds) into the wiki page."""

    revision = "$Rev$"
    url = "$URL$"

    def expand_macro(self, formatter, name, args):
        t = datetime.now(utc)
        return tag.b(format_datetime(t, '%c'))

Macro with arguments

It should be saved as HelloWorld.py (in the plugins/ directory) as Trac will use the module name as the Macro name 

from trac.wiki.macros import WikiMacroBase

class HelloWorldMacro(WikiMacroBase):
    """Simple HelloWorld macro.

    Note that the name of the class is meaningful:
     - it must end with "Macro"
     - what comes before "Macro" ends up being the macro name

    The documentation of the class (i.e. what you're reading)
    will become the documentation of the macro, as shown by
    the !MacroList macro (usually used in the WikiMacros page).
    """

    revision = "$Rev$"
    url = "$URL$"

    def expand_macro(self, formatter, name, args):
        """Return some output that will be displayed in the Wiki content.

        `name` is the actual name of the macro (no surprise, here it'll be
        `'HelloWorld'`),
        `args` is the text enclosed in parenthesis at the call of the macro.
          Note that if there are ''no'' parenthesis (like in, e.g.
          [[HelloWorld]]), then `args` is `None`.
        """
        return 'Hello World, args = ' + unicode(args)
    
    # Note that there's no need to HTML escape the returned data,
    # as the template engine (Genshi) will do it for us.

expand_macro details

expand_macro should return either a simple Python string which will be interpreted as HTML, or preferably a Markup object (use from trac.util.html import Markup). Markup(string) just annotates the string so the renderer will render the HTML string as-is with no escaping. You will also need to import Formatter using from trac.wiki import Formatter.

If your macro creates wiki markup instead of HTML, you can convert it to HTML like this: 

  text = "whatever wiki markup you want, even containing other macros"
  # Convert Wiki markup to HTML, new style
  out = StringIO()
  Formatter(self.env, formatter.context).format(text, out)
  return Markup(out.getvalue())