Changes between Version 16 and Version 17 of CodeExampleMacro


Ignore:
Timestamp:
Apr 16, 2012 3:39:59 AM (3 years ago)
Author:
AdrianFritz
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:'''