source: wiki/pages/WikiRestructuredText @ 37381

Last change on this file since 37381 was 37343, checked in by aafsvn, 8 years ago

[titan] autoupdate wiki files

File size: 4.6 KB
Line 
1= reStructuredText Support in Trac =
2
3Trac supports [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html reStructuredText (RST)] as an alternative to wiki markup where 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 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 ===
11To 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
13Do 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 ==
23To specify that a block of text should be parsed using RST, use the ''rst'' processor.
24
25=== TracLinks in reStructuredText ===
26
27 * Trac provides a custom RST directive `trac::` to allow TracLinks from within RST text.
28   ||= Wiki Markup ||= Display ||
29   {{{#!td
30     {{{
31     {{{
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
54     This is a reference to ticket `#12`:trac:
55
56     To learn how to use Trac, see `TracGuide`:trac:
57     }}}
58     }}}
59   }}}
60   {{{#!td
61     {{{
62     #!rst
63     This is a reference to ticket `#12`:trac:
64
65     To learn how to use Trac, see `TracGuide`:trac:
66     }}}
67   }}}
68
69 For a complete example of all uses of the `:trac:` role, please see WikiRestructuredTextLinks.
70
71=== Syntax highlighting in reStructuredText ===
72
73There is a directive for doing TracSyntaxColoring in RST as well. The directive is called code-block:
74
75||= Wiki Markup ||= Display ||
76{{{#!td
77  {{{
78  {{{
79  #!rst
80
81  .. code-block:: python
82
83     class Test:
84
85         def TestFunction(self):
86             pass
87 
88  }}}
89  }}}
90}}}
91{{{#!td
92  {{{
93  #!rst
94
95  .. code-block:: python
96
97     class Test:
98
99         def TestFunction(self):
100             pass
101
102  }}}
103}}}
104Note the need to indent the code at least one character after the `.. code-block` directive.
105
106=== Wiki Macros in reStructuredText ===
107
108To 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
115
116  .. code-block:: RecentChanges
117
118     Trac,3
119
120  }}}
121  }}}
122}}}
123{{{#!td
124  {{{
125  #!rst
126
127  .. code-block:: RecentChanges
128
129     Trac,3
130
131  }}}
132}}}
133
134Or a more concise Wiki Macro-like syntax is also available, using the `:code-block:` role:
135
136||= Wiki Markup ||= Display ||
137{{{#!td
138  {{{
139  {{{
140  #!rst
141
142  :code-block:`RecentChanges:Trac,3`
143  }}}
144  }}}
145}}}
146{{{#!td
147  {{{
148  #!rst
149
150  :code-block:`RecentChanges:Trac,3`
151  }}}
152}}}
153
154=== Bigger RST Example ===
155The example below should be self-explanatory:
156
157||= Wiki Markup ||= Display ||
158{{{#!td
159{{{
160#!html
161<pre class="wiki">{{{
162#!rst
163FooBar Header
164=============
165reStructuredText is **nice**. It has its own webpage_.
166
167A table:
168
169=====  =====  ======
170   Inputs     Output
171------------  ------
172  A      B    A or B
173=====  =====  ======
174False  False  False
175True   False  True
176False  True   True
177True   True   True
178=====  =====  ======
179
180RST TracLinks
181-------------
182
183See also ticket `#42`:trac:.
184
185.. _webpage: http://docutils.sourceforge.net/rst.html
186}}}</pre>
187}}}
188}}}
189{{{#!td
190{{{
191#!rst
192FooBar Header
193=============
194reStructuredText is **nice**. It has its own webpage_.
195
196A table:
197
198=====  =====  ======
199   Inputs     Output
200------------  ------
201  A      B    A or B
202=====  =====  ======
203False  False  False
204True   False  True
205False  True   True
206True   True   True
207=====  =====  ======
208
209RST TracLinks
210-------------
211
212See also ticket `#42`:trac:.
213
214.. _webpage: http://docutils.sourceforge.net/rst.html
215}}}
216}}}
217
218----
219See also: WikiRestructuredTextLinks, WikiProcessors, WikiFormatting
Note: See TracBrowser for help on using the repository browser.