Changes between Version 16 and Version 17 of CodeExampleMacro


Ignore:
Timestamp:
Apr 16, 2012, 1:39:59 AM (12 years ago)
Author:
Adrian Fritz
Comment:

Page re-factor. Documents installation. Retrieves code documentation (as in [10843]).

Legend:

Unmodified
Added
Removed
Modified

  • CodeExampleMacro

    v16 v17  
    1313All rights reserved by [http://codedgers.com Codedgers Inc.]
    1414
     15== Usage ==
     16
     17  1. Inside a wiki area you can invoke the `#!CodeExample` wiki processor to render a special formatted box containing specified source code, as shown and exemplified down:
     18     {{{
     19     {{{
     20     #!CodeExample
     21     ## parameter = value
     22     ....
     23     ## parameter = value
     24     #!language
     25     ...code...
     26     }}}
     27     }}}
     28     * Where `## parameter = value` can be one or many from:
     29||'''Argument'''[[BR]]  ||'''Version'''[[BR]]  ||'''Required (R)[[BR]]Optional (O)''' ||'''Description'''[[BR]] ||'''Default'''[[BR]]  ||
     30|| `## type`  || || O || A type of box example: `simple`, `good`, `bad` [[BR]]* Example:  {{{ ## type = bad }}} || `simple` ||
     31|| `## title` || || O || The title of the example.[[BR]]* Example:  {{{ ## title = Source from repository A }}}  || If {{{## type = simple}}} then `EXAMPLE:`[[BR]]If {{{## type = good}}} then `CORRECT EXAMPLE:`[[BR]]If {{{## type = bad}}} then `INCORRECT EXAMPLE:` ||
     32|| `## path`  || || O || A file in the repository (using TracLinks format for source code)[[BR]]* Example:  {{{ ## path = GPGMail/Source/GPGMailPreferences.m }}}  || None ||
     33|| `## repo` || || O || Repository to use (Trac 0.12 and upper only).[[BR]]* Example:  {{{ ## repo = T.B.D. }}}  || None ||
     34|| `## regex` || || O || A regular expression indicates where to start an example.[[BR]]* Example:  {{{ ## regex = ".*updater\s*{" }}}  || None ||
     35|| `## lines` || || O || Number of lines to show.[[BR]]* Example:  {{{ ## lines = 3 }}}  || None ||
     36|| `#!language` || || O || Syntax highlighter. `language` is any supported by Trac. See TracSyntaxColoring.[[BR]]* Example:  {{{ #!python }}}  || `trac` ||
     37  2. The simple example:
     38     {{{
     39     {{{
     40     #!CodeExample
     41     #!python
     42     @staticmethod
     43     def get_templates_dirs():
     44         """ Notify Trac about templates dir. """
     45         from pkg_resources import resource_filename
     46         return [resource_filename(__name__, 'templates')]
     47     }}}
     48     }}}
     49     * will be rendered as:
     50      [[Image(example1.png)]]
     51  1. The incorrect example:
     52     {{{
     53     {{{
     54     #!CodeExample
     55     ## type = bad
     56     #!haskell
     57     fibs = 0 : 1 : [ a + b | a <- fibs | b <- tail fibs ]
     58     }}}
     59     }}}
     60     * will be rendered as:
     61       [[Image(example2.png)]]
     62  1. The correct example:
     63     {{{
     64     {{{
     65     #!CodeExample
     66     ## type = good
     67     #!haskell
     68     fibs = 0 : 1 : zipWith (+) fibs (tail fibs)
     69     }}}
     70     }}}
     71     * will be rendered as:
     72       [[Image(example3.png)]]
     73  1. There is also support for getting sources from the repository:
     74     {{{
     75     {{{
     76     #!CodeExample
     77     ## path=GPGMail/Source/GPGMailPreferences.m
     78     ## regex=".*updater\s*{"
     79     ## lines=3
     80     #!objective-c
     81     }}}
     82     }}}
     83     * will be rendered as:
     84       [[Image(example4.png)]][[BR]][[BR]]
     85
     86== Installation ==
     87
     88  {{{
     89  #!comment
     90  1. '''Check''' dependencies:
     91     i. none required
     92
     93     * ,,`[sudo]` is optional case you already have enough authority to modify your server.,,[[BR]][[BR]]
     94  }}}
     95  1. '''Install''' plugin globally:
     96     * with easy_install:
     97       {{{
     98       #!sh
     99       $ [sudo] easy_install https://trac-hacks.org/svn/codeexamplemacro
     100       }}}
     101        * ,,`[sudo]` is optional case you already have enough authority to modify your server.,,
     102        * ,,You might be required to select a specific `tag`, `branch`. Defaults to select from `trunk`,,[[BR]][[BR]]
     103  1. '''Enable''' this component by updating TracIni file as follows:
     104     {{{
     105     [components]
     106     codeexample.code_example_processor.* = enabled
     107     }}}
     108  {{{
     109  #!comment
     110  1. '''Configure''' this component in its own configuration section, by updating TracIni file as follows:
     111     i. none required
     112     {{{
     113     [plantuml]
     114     plantuml_jar = /path/to/plantuml.jar
     115     java_bin = /path/to/java_bin (optional, if Java binary is not on the search path)
     116     }}}
     117     * example `plantuml_jar = /project-resources/trac/plugins`
     118     * example `java_bin = java` assumes that the Java binary is on the search path.[[BR]][[BR]]
     119  }}}
     120  1. '''Restart''' web server on command line:
     121     {{{
     122     #!sh
     123     $ [sudo] /etc/init.d/apache2 restart
     124     }}}
     125       * ,,`[sudo]` is optional case you already have enough authority to modify your server.,,[[BR]][[BR]]
     126  1. '''Test''' if this component is working properly.
     127     1. If the plugin is installed correct, the example shown in the [#Usage] section on this page should be displayed.[[BR]][[BR]]
     128
    15129== Bugs/Feature Requests ==
    16130
    17 Existing bugs and feature requests for CodeExampleMacro are [report:9?COMPONENT=CodeExampleMacro here].
     131Existing '''[report:9?COMPONENT=CodeExampleMacro bugs and feature requests]''' for !CodeExampleMacro.
    18132
    19 If you have any issues, create a [http://trac-hacks.org/newticket?component=CodeExampleMacro&owner=nuald new ticket].
     133If you have any issues, create a '''[/newticket?component=CodeExampleMacro&cc=rjollos&owner=nuald new ticket]'''.
    20134
    21 == Download ==
     135== Source & Download ==
    22136
    23 Download the zipped source from [download:codeexamplemacro here].
     137You can '''[http://trac-hacks.org/svn/codeexamplemacro check out]''' !PCodeExampleMacro using Subversion, or '''[source:codeexamplemacro browse the source]''' with Trac, or '''[download:codeexamplemacro download]''' the zipped source.
    24138
    25 == Source ==
    26 
    27 You can check out CodeExampleMacro from [http://trac-hacks.org/svn/codeexamplemacro here] using Subversion, or [source:codeexamplemacro browse the source] with Trac.
    28 
    29 == Example ==
    30 
    31 The simple example:
    32 {{{
    33 {{{
    34 #!CodeExample
    35 #!python
    36 @staticmethod
    37 def get_templates_dirs():
    38     """ Notify Trac about templates dir. """
    39     from pkg_resources import resource_filename
    40     return [resource_filename(__name__, 'templates')]
    41 }}}
    42 }}}
    43 
    44 will be rendered as:
    45 
    46 [[Image(example1.png)]]
    47 
    48 The incorrect example:
    49 {{{
    50 {{{
    51 #!CodeExample
    52 ## type = bad
    53 #!haskell
    54 fibs = 0 : 1 : [ a + b | a <- fibs | b <- tail fibs ]
    55 }}}
    56 }}}
    57 
    58 will be rendered as:
    59 
    60 [[Image(example2.png)]]
    61 
    62 The correct example:
    63 {{{
    64 {{{
    65 #!CodeExample
    66 ## type = good
    67 #!haskell
    68 fibs = 0 : 1 : zipWith (+) fibs (tail fibs)
    69 }}}
    70 }}}
    71 
    72 will be rendered as:
    73 
    74 [[Image(example3.png)]]
    75 
    76 There is also support for getting sources from the repository:
    77 {{{
    78 {{{
    79 #!CodeExample
    80 ## path=GPGMail/Source/GPGMailPreferences.m
    81 ## regex=".*updater\s*{"
    82 ## lines=3
    83 #!objective-c
    84 }}}
    85 }}}
    86 
    87 will be rendered as:
    88 
    89 [[Image(example4.png)]]
    90 
    91 Parameters:
    92 || '''type'''  || optional || a type of the example: simple (default), good, bad ||
    93 || '''title''' || optional || the title of the example ||
    94 || '''path'''  || optional || a file in the repository (using TracLinks format for source code) ||
    95 || '''repo'''  || optional || repository to use (Trac 0.12 and upper only) ||
    96 || '''regex''' || optional || a regular expression indicates where to start an example ||
    97 || '''lines''' || optional || number of lines to show ||
    98 
    99 == Recent Changes ==
     139=== Recent Changes ===
    100140
    101141[[ChangeLog(codeexamplemacro, 3)]]
    … …  
    104144
    105145'''Author:''' [wiki:nuald] [[BR]]
    106 '''Maintainer:''' [wiki:nuald] [[BR]]
     146'''Maintainer:''' [wiki:nuald], [wiki:rjollos] [[BR]]
    107147'''Contributors:'''