Changes between Version 1 and Version 2 of WikiRestructuredText
- Timestamp:
- Jun 6, 2024, 9:53:06 AM (6 months ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
WikiRestructuredText
v1 v2 1 = reStructuredText Support in Trac = 1 = reStructuredText Support in Trac 2 3 == Introduction 4 2 5 3 6 Trac supports [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html reStructuredText (RST)] as an alternative to wiki markup where WikiFormatting is used. 4 7 5 8 From the reStucturedText webpage: 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 to be displayed as reStructuredText in the Trac source browser, set `text/x-rst` as the value for the Subversion property `svn:mime-type` . See [trac:source:/trunk/INSTALLthis example].9 10 === Requirements === 11 To activate RST support in Trac, install the python docutils package: `easy_install docutils`. If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website]. 12 13 Do not use the package manager of your OS, eg `apt-get install python-docutils`, because Trac will not find docutils then. 14 15 === More information on RST === 16 17 * reStructuredText Website -- http://docutils.sourceforge.net/rst.html 18 * RST Quick Reference -- http://docutils.sourceforge.net/docs/rst/quickref.html19 20 ---- 21 22 == Using RST in Trac == 9 "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." 10 11 If you want a file from your Subversion repository to be displayed as reStructuredText in the Trac source browser, set `text/x-rst` as the value for the Subversion property `svn:mime-type`, or add the extension `rst` to the filename. See [trac:source:/trunk/INSTALL.rst this example]. 12 13 The examples will only be rendered as reStructuredText if docutils is installed. If Pygments is installed but docutils is not installed, the examples will be syntax-highlighted rather than rendered as reStructuredText. 14 15 === Requirements 16 17 To activate RST support in Trac, install the python docutils package with the command `easy_install docutils`, or through your operating system package manager. If not already available on your operating system, you can download it from [https://pypi.python.org/pypi/docutils PyPI]. 18 19 === More information on RST 20 21 * [http://docutils.sourceforge.net/rst.html reStructuredText Website] 22 * [http://docutils.sourceforge.net/docs/rst/quickref.html RST Quick Reference] 23 24 == Using RST in Trac 25 23 26 To specify that a block of text should be parsed using RST, use the ''rst'' processor. 24 27 25 === TracLinks in reStructuredText ===28 === TracLinks in reStructuredText 26 29 27 30 * Trac provides a custom RST directive `trac::` to allow TracLinks from within RST text. … … 29 32 {{{#!td 30 33 {{{ 34 {{{#!rst 35 This is a reference to |a ticket| 36 37 .. |a ticket| trac:: #42 38 }}} 39 }}} 40 }}} 41 {{{#!td 42 {{{#!rst 43 This is a reference to |a ticket| 44 45 .. |a ticket| trac:: #42 46 }}} 47 }}} 48 49 * You can also use the custom `:trac:` role to create TracLinks in RST. 50 ||= Wiki Markup ||= Display || 51 {{{#!td 31 52 {{{ 32 #!rst 33 This is a reference to |a ticket| 34 35 .. |a ticket| trac:: #42 36 }}} 37 }}} 38 }}} 39 {{{#!td 40 {{{ 41 #!rst 42 This is a reference to |a ticket| 43 44 .. |a ticket| trac:: #42 45 }}} 46 }}} 47 48 * Trac allows an even easier way of creating TracLinks in RST, using the custom `:trac:` role. 49 ||= Wiki Markup ||= Display || 50 {{{#!td 51 {{{ 52 {{{ 53 #!rst 53 {{{#!rst 54 54 This is a reference to ticket `#12`:trac: 55 55 … … 59 59 }}} 60 60 {{{#!td 61 {{{ 62 #!rst 61 {{{#!rst 63 62 This is a reference to ticket `#12`:trac: 64 63 … … 67 66 }}} 68 67 69 For a complete example of all uses of the `:trac:` role, pleasesee WikiRestructuredTextLinks.70 71 === Syntax highlighting in reStructuredText ===68 For a complete example of all uses of the `:trac:` role, see WikiRestructuredTextLinks. 69 70 === Syntax highlighting in reStructuredText 72 71 73 72 There is a directive for doing TracSyntaxColoring in RST as well. The directive is called code-block: … … 76 75 {{{#!td 77 76 {{{ 78 {{{ 79 #!rst 77 {{{#!rst 80 78 81 79 .. code-block:: python … … 90 88 }}} 91 89 {{{#!td 92 {{{ 93 #!rst 90 {{{#!rst 94 91 95 92 .. code-block:: python … … 104 101 Note the need to indent the code at least one character after the `.. code-block` directive. 105 102 106 === Wiki Macros in reStructuredText === 107 108 To enable [WikiMacros Wiki Macros] in RST, you use the same directive as for syntax highlighting, ie code-block: 103 === Wiki Macros in reStructuredText 104 105 To enable [WikiMacros Wiki Macros] in RST, you use the same `code-block` directive as for syntax highlighting: 106 107 ||= Wiki Markup ||= Display || 108 {{{#!td 109 {{{ 110 {{{#!rst 111 112 .. code-block:: RecentChanges 113 114 Trac,3 115 116 }}} 117 }}} 118 }}} 119 {{{#!td 120 {{{#!rst 121 122 .. code-block:: RecentChanges 123 124 Trac,3 125 126 }}} 127 }}} 128 129 Or use the `:code-block:` role for a more concise Wiki Macro-like syntax: 109 130 110 131 ||= Wiki Markup ||= Display || … … 114 135 #!rst 115 136 116 .. code-block:: RecentChanges117 118 Trac,3119 120 }}}121 }}}122 }}}123 {{{#!td124 {{{125 #!rst126 127 .. code-block:: RecentChanges128 129 Trac,3130 131 }}}132 }}}133 134 Or a more concise Wiki Macro-like syntax is also available, using the `:code-block:` role:135 136 ||= Wiki Markup ||= Display ||137 {{{#!td138 {{{139 {{{140 #!rst141 142 137 :code-block:`RecentChanges:Trac,3` 143 138 }}} … … 145 140 }}} 146 141 {{{#!td 147 {{{ 148 #!rst 142 {{{#!rst 149 143 150 144 :code-block:`RecentChanges:Trac,3` … … 152 146 }}} 153 147 154 === Bigger RST Example === 148 === Bigger RST Example 149 155 150 The example below should be self-explanatory: 156 151 157 152 ||= Wiki Markup ||= Display || 158 153 {{{#!td 159 {{{ 160 #!html 161 <pre class="wiki">{{{ 162 #!rst 154 {{{#!html 155 <pre class="wiki">{{{#!rst 163 156 FooBar Header 164 157 ============= … … 188 181 }}} 189 182 {{{#!td 190 {{{ 191 #!rst 183 {{{#!rst 192 184 FooBar Header 193 185 =============