close
Warning:
Can't synchronize with repository "(default)" (/hepforge/svn/w2pho does not appear to be a Subversion repository.). Look in the Trac log for more information.
- Timestamp:
-
Feb 27, 2012, 2:25:34 PM (13 years ago)
- Author:
-
trac
- Comment:
-
--
Legend:
- Unmodified
- Added
- Removed
- Modified
-
v1
|
v2
|
|
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 | |
| 8 | If 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]. |
7 | 9 | |
8 | 10 | === Requirements === |
… |
… |
|
10 | 12 | If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website]. |
11 | 13 | |
| 14 | 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. |
| 15 | |
12 | 16 | === More information on RST === |
13 | 17 | |
… |
… |
|
22 | 26 | === TracLinks in reStructuredText === |
23 | 27 | |
24 | | * Trac provides a custom RST reference-directive 'trac' to allow TracLinks from within RST text. |
25 | | |
26 | | Example: |
27 | | {{{ |
28 | | {{{ |
29 | | #!rst |
30 | | This is a reference to |a ticket| |
31 | | |
32 | | .. |a ticket| trac:: #42 |
33 | | }}} |
34 | | }}} |
35 | | |
36 | | For a complete example of all uses of the ''trac''-directive, please see WikiRestructuredTextLinks. |
37 | | |
38 | | |
39 | | * Trac allows an even easier way of creating TracLinks in RST, using the custom '':trac:'' link naming scheme. |
40 | | |
41 | | Example: |
42 | | {{{ |
43 | | {{{ |
44 | | #!rst |
45 | | This is a reference to ticket `#12`:trac: |
46 | | |
47 | | To learn how to use Trac, see `TracGuide`:trac: |
48 | | }}} |
49 | | }}} |
| 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 | |
50 | 72 | |
51 | 73 | === Syntax highlighting in reStructuredText === |
52 | 74 | |
53 | | There is a directive for doing TracSyntaxColoring in ReST as well. The directive is called |
| 75 | There is a directive for doing TracSyntaxColoring in RST as well. The directive is called |
54 | 76 | code-block |
55 | 77 | |
56 | | Example |
57 | | |
58 | | {{{ |
59 | | {{{ |
60 | | #!rst |
61 | | |
62 | | .. code-block:: python |
63 | | |
64 | | class Test: |
65 | | |
66 | | def TestFunction(self): |
67 | | pass |
68 | | |
69 | | }}} |
70 | | }}} |
71 | | |
72 | | Will result in the below. |
73 | | |
74 | | {{{ |
75 | | #!rst |
76 | | |
77 | | .. code-block:: python |
78 | | |
79 | | class Test: |
80 | | |
81 | | def TestFunction(self): |
82 | | pass |
83 | | |
84 | | }}} |
85 | | |
86 | | === WikiMacros in reStructuredText === |
87 | | |
88 | | For doing WikiMacros in ReST you use the same directive as for syntax highlightning i.e |
89 | | code-block. To work you must use a version of trac that has #801 applied. |
90 | | |
91 | | === WikiMacro Example === |
92 | | |
93 | | {{{ |
94 | | {{{ |
95 | | #!rst |
96 | | |
97 | | .. code-block:: HelloWorld |
98 | | |
99 | | Something I wanted to say |
100 | | |
101 | | |
102 | | }}} |
103 | | }}} |
104 | | |
105 | | Will result in the below. |
106 | | |
107 | | [[HelloWorld(Something I wanted to say)]] |
108 | | |
109 | | |
110 | | === Bigger ReST Example === |
| 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 | }}} |
| 107 | Note the need to indent the code at least one character after the `.. code-block` directive. |
| 108 | |
| 109 | === Wiki Macros in reStructuredText === |
| 110 | |
| 111 | For 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 | |
| 137 | Or 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 === |
111 | 158 | The example below should be mostly self-explanatory: |
| 159 | |
| 160 | ||= Wiki Markup ||= Display || |
| 161 | {{{#!td |
112 | 162 | {{{ |
113 | 163 | #!html |
… |
… |
|
139 | 189 | }}}</pre> |
140 | 190 | }}} |
141 | | |
142 | | |
143 | | Results in: |
| 191 | }}} |
| 192 | {{{#!td |
144 | 193 | {{{ |
145 | 194 | #!rst |
… |
… |
|
168 | 217 | .. _webpage: http://docutils.sourceforge.net/rst.html |
169 | 218 | }}} |
170 | | |
| 219 | }}} |
171 | 220 | |
172 | 221 | ---- |