Changes between Version 2 and Version 3 of WikiRestructuredText
- Timestamp:
- 2019-05-02T09:45:05-03:00 (5 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
WikiRestructuredText
v2 v3 1 = reStructuredText Support in Trac 2 3 == Introduction 4 1 = reStructuredText Support in Trac = 5 2 6 3 Trac supports [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html reStructuredText (RST)] as an alternative to wiki markup where WikiFormatting is used. 7 4 8 5 From the reStucturedText webpage: 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.rstthis 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 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/INSTALL this 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.html 19 20 ---- 21 22 == Using RST in Trac == 26 23 To specify that a block of text should be parsed using RST, use the ''rst'' processor. 27 24 28 === TracLinks in reStructuredText 25 === TracLinks in reStructuredText === 29 26 30 27 * Trac provides a custom RST directive `trac::` to allow TracLinks from within RST text. … … 32 29 {{{#!td 33 30 {{{ 34 {{{#!rst 31 {{{ 32 #!rst 35 33 This is a reference to |a ticket| 36 34 … … 40 38 }}} 41 39 {{{#!td 42 {{{#!rst 40 {{{ 41 #!rst 43 42 This is a reference to |a ticket| 44 43 … … 47 46 }}} 48 47 49 * You can also use the custom `:trac:` role to create TracLinks in RST.48 * Trac allows an even easier way of creating TracLinks in RST, using the custom `:trac:` role. 50 49 ||= Wiki Markup ||= Display || 51 50 {{{#!td 52 51 {{{ 53 {{{#!rst 52 {{{ 53 #!rst 54 54 This is a reference to ticket `#12`:trac: 55 55 … … 59 59 }}} 60 60 {{{#!td 61 {{{#!rst 61 {{{ 62 #!rst 62 63 This is a reference to ticket `#12`:trac: 63 64 … … 66 67 }}} 67 68 68 For a complete example of all uses of the `:trac:` role, see WikiRestructuredTextLinks.69 70 === Syntax highlighting in reStructuredText 69 For a complete example of all uses of the `:trac:` role, please see WikiRestructuredTextLinks. 70 71 === Syntax highlighting in reStructuredText === 71 72 72 73 There is a directive for doing TracSyntaxColoring in RST as well. The directive is called code-block: … … 75 76 {{{#!td 76 77 {{{ 77 {{{#!rst 78 {{{ 79 #!rst 78 80 79 81 .. code-block:: python … … 88 90 }}} 89 91 {{{#!td 90 {{{#!rst 92 {{{ 93 #!rst 91 94 92 95 .. code-block:: python … … 101 104 Note the need to indent the code at least one character after the `.. code-block` directive. 102 105 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 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: 109 110 ||= Wiki Markup ||= Display || 111 {{{#!td 112 {{{ 113 {{{ 114 #!rst 111 115 112 116 .. code-block:: RecentChanges … … 118 122 }}} 119 123 {{{#!td 120 {{{#!rst 124 {{{ 125 #!rst 121 126 122 127 .. code-block:: RecentChanges … … 127 132 }}} 128 133 129 Or use the `:code-block:` role for a more concise Wiki Macro-like syntax:134 Or a more concise Wiki Macro-like syntax is also available, using the `:code-block:` role: 130 135 131 136 ||= Wiki Markup ||= Display || … … 140 145 }}} 141 146 {{{#!td 142 {{{#!rst 147 {{{ 148 #!rst 143 149 144 150 :code-block:`RecentChanges:Trac,3` … … 146 152 }}} 147 153 148 === Bigger RST Example 149 154 === Bigger RST Example === 150 155 The example below should be self-explanatory: 151 156 152 157 ||= Wiki Markup ||= Display || 153 158 {{{#!td 154 {{{#!html 155 <pre class="wiki">{{{#!rst 159 {{{ 160 #!html 161 <pre class="wiki">{{{ 162 #!rst 156 163 FooBar Header 157 164 ============= … … 181 188 }}} 182 189 {{{#!td 183 {{{#!rst 190 {{{ 191 #!rst 184 192 FooBar Header 185 193 =============
