Changes between Version 1 and Version 2 of WikiRestructuredText
- Timestamp:
- 09/29/11 01:15:08 (13 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
WikiRestructuredText
v1 v2 5 5 From the reStucturedText webpage: 6 6 "''reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. reStructuredText is designed for extensibility for specific application domains. ''" 7 8 If you want a file from your Subversion repository be displayed as reStructuredText in Trac's source browser, set `text/x-rst` as value for the Subversion property `svn:mime-type`. See [trac:source:/trunk/INSTALL this example]. 7 9 8 10 === Requirements === … … 10 12 If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website]. 11 13 14 Install docutils using `easy_install docutils`. Do not use the package manager of your OS (e.g. `apt-get install python-docutils`), because Trac will not find docutils then. 15 12 16 === More information on RST === 13 17 … … 22 26 === TracLinks in reStructuredText === 23 27 24 * Trac provides a custom RST reference-directive 'trac' to allow TracLinks from within RST text. 25 26 Example: 27 {{{ 28 {{{ 29 #!rst 30 This is a reference to |a ticket| 31 32 .. |a ticket| trac:: #42 33 }}} 34 }}} 35 36 For a complete example of all uses of the ''trac''-directive, please see WikiRestructuredTextLinks. 37 38 39 * Trac allows an even easier way of creating TracLinks in RST, using the custom '':trac:'' link naming scheme. 40 41 Example: 42 {{{ 43 {{{ 44 #!rst 45 This is a reference to ticket `#12`:trac: 46 47 To learn how to use Trac, see `TracGuide`:trac: 48 }}} 49 }}} 28 * Trac provides a custom RST directive `trac::` to allow TracLinks from within RST text. 29 ||= Wiki Markup ||= Display || 30 {{{#!td 31 {{{ 32 {{{ 33 #!rst 34 This is a reference to |a ticket| 35 36 .. |a ticket| trac:: #42 37 }}} 38 }}} 39 }}} 40 {{{#!td 41 {{{ 42 #!rst 43 This is a reference to |a ticket| 44 45 .. |a ticket| trac:: #42 46 }}} 47 }}} 48 49 * Trac allows an even easier way of creating TracLinks in RST, using the custom `:trac:` role. 50 ||= Wiki Markup ||= Display || 51 {{{#!td 52 {{{ 53 {{{ 54 #!rst 55 This is a reference to ticket `#12`:trac: 56 57 To learn how to use Trac, see `TracGuide`:trac: 58 }}} 59 }}} 60 }}} 61 {{{#!td 62 {{{ 63 #!rst 64 This is a reference to ticket `#12`:trac: 65 66 To learn how to use Trac, see `TracGuide`:trac: 67 }}} 68 }}} 69 70 For a complete example of all uses of the `:trac:` role, please see WikiRestructuredTextLinks. 71 50 72 51 73 === Syntax highlighting in reStructuredText === 52 74 53 There is a directive for doing TracSyntaxColoring in R eST as well. The directive is called75 There is a directive for doing TracSyntaxColoring in RST as well. The directive is called 54 76 code-block 55 77 56 Example 57 58 {{{ 59 {{{ 60 #!rst 61 62 .. code-block:: python 63 64 class Test: 65 66 def TestFunction(self): 67 pass 68 69 }}} 70 }}} 71 72 Will result in the below. 73 74 {{{ 75 #!rst 76 77 .. code-block:: python 78 79 class Test: 80 81 def TestFunction(self): 82 pass 83 84 }}} 78 ||= Wiki Markup ||= Display || 79 {{{#!td 80 {{{ 81 {{{ 82 #!rst 83 84 .. code-block:: python 85 86 class Test: 87 88 def TestFunction(self): 89 pass 90 91 }}} 92 }}} 93 }}} 94 {{{#!td 95 {{{ 96 #!rst 97 98 .. code-block:: python 99 100 class Test: 101 102 def TestFunction(self): 103 pass 104 105 }}} 106 }}} 107 Note the need to indent the code at least one character after the `.. code-block` directive. 85 108 86 109 === Wiki Macros in reStructuredText === 87 110 88 For doing [TracWikiMacros Wiki Macros] in ReST you use the same directive as for syntax highlighting i.e 89 code-block. To work you must use a version of trac that has #801 applied. 90 91 === Wiki Macro Example === 92 93 {{{ 94 {{{ 95 #!rst 96 97 .. code-block:: HelloWorld 98 99 Something I wanted to say 100 101 102 }}} 103 }}} 104 105 Will result in the below: 106 107 [[HelloWorld(Something I wanted to say)]] 108 109 Or a more concise WikiMacro like syntax is also available: 110 111 {{{ 112 {{{ 113 #!rst 114 115 :code-block:`HelloWorld:Something I wanted to say` 116 }}} 117 }}} 118 119 === Bigger ReST Example === 111 For doing [WikiMacros Wiki Macros] in RST you use the same directive as for syntax highlighting i.e code-block. 112 113 ||= Wiki Markup ||= Display || 114 {{{#!td 115 {{{ 116 {{{ 117 #!rst 118 119 .. code-block:: RecentChanges 120 121 Trac,3 122 123 }}} 124 }}} 125 }}} 126 {{{#!td 127 {{{ 128 #!rst 129 130 .. code-block:: RecentChanges 131 132 Trac,3 133 134 }}} 135 }}} 136 137 Or a more concise Wiki Macro like syntax is also available, using the `:code-block:` role: 138 139 ||= Wiki Markup ||= Display || 140 {{{#!td 141 {{{ 142 {{{ 143 #!rst 144 145 :code-block:`RecentChanges:Trac,3` 146 }}} 147 }}} 148 }}} 149 {{{#!td 150 {{{ 151 #!rst 152 153 :code-block:`RecentChanges:Trac,3` 154 }}} 155 }}} 156 157 === Bigger RST Example === 120 158 The example below should be mostly self-explanatory: 159 160 ||= Wiki Markup ||= Display || 161 {{{#!td 121 162 {{{ 122 163 #!html … … 148 189 }}}</pre> 149 190 }}} 150 151 152 Results in: 191 }}} 192 {{{#!td 153 193 {{{ 154 194 #!rst … … 177 217 .. _webpage: http://docutils.sourceforge.net/rst.html 178 218 }}} 179 219 }}} 180 220 181 221 ----