source: wiki/pages/WikiRestructuredText @ 28930

Last change on this file since 28930 was 26484, checked in by obi, 10 years ago

add wiki pages

File size: 4.6 KB
Line 
1= reStructuredText Support in Trac =
2
3Trac supports using ''reStructuredText'' (RST) as an alternative to wiki markup in any context WikiFormatting is used.
4
5From 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
8If 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].
9
10=== Requirements ===
11Note that to activate RST support in Trac, the python docutils package must be installed.
12If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website].
13
14Install 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
16=== More information on RST ===
17
18 * reStructuredText Website -- http://docutils.sourceforge.net/rst.html
19 * RST Quick Reference -- http://docutils.sourceforge.net/docs/rst/quickref.html
20
21----
22
23== Using RST in Trac ==
24To specify that a block of text should be parsed using RST, use the ''rst'' processor.
25
26=== TracLinks in reStructuredText ===
27
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
72
73=== Syntax highlighting in reStructuredText ===
74
75There is a directive for doing TracSyntaxColoring in RST as well. The directive is called
76code-block
77
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}}}
107Note the need to indent the code at least one character after the `.. code-block` directive.
108
109=== Wiki Macros in reStructuredText ===
110
111For 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
137Or 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 ===
158The example below should be mostly self-explanatory:
159
160||= Wiki Markup ||= Display ||
161{{{#!td
162{{{
163#!html
164<pre class="wiki">{{{
165#!rst
166FooBar Header
167=============
168reStructuredText is **nice**. It has its own webpage_.
169
170A table:
171
172=====  =====  ======
173   Inputs     Output
174------------  ------
175  A      B    A or B
176=====  =====  ======
177False  False  False
178True   False  True
179False  True   True
180True   True   True
181=====  =====  ======
182
183RST TracLinks
184-------------
185
186See also ticket `#42`:trac:.
187
188.. _webpage: http://docutils.sourceforge.net/rst.html
189}}}</pre>
190}}}
191}}}
192{{{#!td
193{{{
194#!rst
195FooBar Header
196=============
197reStructuredText is **nice**. It has its own webpage_.
198
199A table:
200
201=====  =====  ======
202   Inputs     Output
203------------  ------
204  A      B    A or B
205=====  =====  ======
206False  False  False
207True   False  True
208False  True   True
209True   True   True
210=====  =====  ======
211
212RST TracLinks
213-------------
214
215See also ticket `#42`:trac:.
216
217.. _webpage: http://docutils.sourceforge.net/rst.html
218}}}
219}}}
220
221----
222See also: WikiRestructuredTextLinks, WikiProcessors, WikiFormatting
Note: See TracBrowser for help on using the repository browser.