close
Warning:
Can't synchronize with repository "(default)" (/srv/svn/repos/chg does not appear to be a Subversion repository.). Look in the Trac log for more information.
- Timestamp:
-
Jul 21, 2015, 11:34:14 AM (9 years ago)
- Author:
-
trac
- Comment:
-
--
Legend:
- Unmodified
- Added
- Removed
- Modified
-
v1
|
v2
|
|
1 | 1 | = reStructuredText Support in Trac = |
2 | 2 | |
3 | | Trac supports using ''reStructuredText'' (RST) as an alternative to wiki markup in any context WikiFormatting is used. |
| 3 | Trac supports [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html reStructuredText (RST)] as an alternative to wiki markup where WikiFormatting is used. |
4 | 4 | |
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 | 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 | |
8 | 10 | === Requirements === |
9 | | Note that to activate RST support in Trac, the python docutils package must be installed. |
10 | | If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website]. |
11 | | |
12 | | 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. |
| 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. |
13 | 14 | |
14 | 15 | === More information on RST === |
… |
… |
|
25 | 26 | |
26 | 27 | * Trac provides a custom RST directive `trac::` to allow TracLinks from within RST text. |
27 | | |
28 | | Example: |
29 | | {{{ |
30 | | {{{ |
31 | | #!rst |
32 | | This is a reference to |a ticket| |
33 | | |
34 | | .. |a ticket| trac:: #42 |
35 | | }}} |
36 | | }}} |
| 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 | }}} |
37 | 47 | |
38 | 48 | * Trac allows an even easier way of creating TracLinks in RST, using the custom `:trac:` role. |
39 | | |
40 | | Example: |
41 | | {{{ |
42 | | {{{ |
43 | | #!rst |
44 | | This is a reference to ticket `#12`:trac: |
45 | | |
46 | | To learn how to use Trac, see `TracGuide`:trac: |
47 | | }}} |
48 | | }}} |
| 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 | }}} |
49 | 68 | |
50 | 69 | For a complete example of all uses of the `:trac:` role, please see WikiRestructuredTextLinks. |
51 | 70 | |
52 | | |
53 | 71 | === Syntax highlighting in reStructuredText === |
54 | 72 | |
55 | | There is a directive for doing TracSyntaxColoring in RST as well. The directive is called |
56 | | code-block |
57 | | |
58 | | Example |
59 | | |
60 | | {{{ |
61 | | {{{ |
62 | | #!rst |
63 | | |
64 | | .. code-block:: python |
65 | | |
66 | | class Test: |
67 | | |
68 | | def TestFunction(self): |
69 | | pass |
70 | | |
71 | | }}} |
72 | | }}} |
73 | | |
74 | | Will result in the below. |
75 | | |
76 | | {{{ |
77 | | #!rst |
78 | | |
79 | | .. code-block:: python |
80 | | |
81 | | class Test: |
82 | | |
83 | | def TestFunction(self): |
84 | | pass |
85 | | |
86 | | }}} |
| 73 | There 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 | }}} |
| 104 | Note the need to indent the code at least one character after the `.. code-block` directive. |
87 | 105 | |
88 | 106 | === Wiki Macros in reStructuredText === |
89 | 107 | |
90 | | For doing [WikiMacros Wiki Macros] in RST you use the same directive as for syntax highlighting i.e |
91 | | code-block. To work you must use a version of trac that has [trac:ticket:801 #801] applied. |
92 | | |
93 | | === Wiki Macro Example === |
94 | | |
95 | | {{{ |
96 | | {{{ |
97 | | #!rst |
98 | | |
99 | | .. code-block:: RecentChanges |
100 | | |
101 | | Trac,3 |
102 | | |
103 | | }}} |
104 | | }}} |
105 | | |
106 | | Will result in the below: |
107 | | |
108 | | [[RecentChanges(Trac,3)]] |
109 | | |
110 | | Or a more concise Wiki Macro like syntax is also available: |
111 | | |
112 | | {{{ |
113 | | {{{ |
114 | | #!rst |
115 | | |
116 | | :code-block:`RecentChanges:Trac,3` |
117 | | }}} |
| 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 |
| 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 | |
| 134 | Or 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 | }}} |
118 | 152 | }}} |
119 | 153 | |
120 | 154 | === Bigger RST Example === |
121 | | The example below should be mostly self-explanatory: |
| 155 | The example below should be self-explanatory: |
| 156 | |
| 157 | ||= Wiki Markup ||= Display || |
| 158 | {{{#!td |
122 | 159 | {{{ |
123 | 160 | #!html |
… |
… |
|
149 | 186 | }}}</pre> |
150 | 187 | }}} |
151 | | |
152 | | |
153 | | Results in: |
| 188 | }}} |
| 189 | {{{#!td |
154 | 190 | {{{ |
155 | 191 | #!rst |
… |
… |
|
178 | 214 | .. _webpage: http://docutils.sourceforge.net/rst.html |
179 | 215 | }}} |
180 | | |
| 216 | }}} |
181 | 217 | |
182 | 218 | ---- |