1 | | = Trac での reStructuredText 対応 = #reStructuredTextSupportinTrac |
2 | | |
3 | | Trac は WikiFormatting を使用できるすべての箇所で、 Wiki マークアップの代わりに ''reStructuredText'' を使用することができます。 |
4 | | |
5 | | reStructuredText の Web ページより: |
6 | | "''reStructuredText は読みやすく、 WYSIWYG なプレーンテキストへのマークアップ文法と、そのパーサシステムです。 (Python の docstring のような) プログラムへのインラインドキュメンテーションや、シンプルな Web ページの素早い作成、スタンドアロンのドキュメントの記述に役立ちます。 reStructuredText は個別のアプリケーション向けに拡張ができるように設計されています。''" |
7 | | |
8 | | === 必須条件 === #Requirements |
9 | | Trac で RST を使うためには、 Python の docutils パッケージがインストールされていなければなりません。 |
10 | | あなたのオペレーティングシステムでまだ使用できない場合は、 [http://docutils.sourceforge.net/rst.html RST Website] からダウンロードすることができます。 |
11 | | |
12 | | docutils のインストールには `easy_install docutils` を使用してください。 Trac が docutils パッケージを探すことが出来ない可能性があるので、 (`apt-get install python-docutils` などの) OS のパッケージマネージャは使わないでください。 |
13 | | ('''訳注:''' docutils が提供している `setup.py` では `setuptools` を使用していないため、 OS のパッケージでは `docutils-*.egg-info` が作成されない場合があることを指しています。 egg-info さえ作成されていれば OS のパッケージマネージャを使用しても問題ないと思われます。) |
14 | | |
15 | | === さらなる RST に関する情報 === #MoreinformationonRST |
16 | | |
17 | | * reStructuredText Web サイト -- http://docutils.sourceforge.net/rst.html |
18 | | * RST クイックリファレンス -- http://docutils.sourceforge.net/docs/rst/quickref.html |
| 1 | = reStructuredText Support in Trac = |
| 2 | |
| 3 | Trac supports using ''reStructuredText'' (RST) as an alternative to wiki markup in any context WikiFormatting is used. |
| 4 | |
| 5 | From 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 | |
| 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]. |
| 9 | |
| 10 | === Requirements === |
| 11 | Note that to activate RST support in Trac, the python docutils package must be installed. |
| 12 | If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website]. |
| 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 | |
| 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 |
22 | | == RST を Trac で使用する == #UsingRSTinTrac |
23 | | テキストブロックが RST でパースされるようにするには、 ''rst'' プロセッサを使用してください。 |
24 | | |
25 | | === reStructuredText における TracLinks === #TracLinksinreStructuredText |
26 | | |
27 | | * Trac は RST テキストの中で TracLinks が可能になる、 RST のリファレンスディレクティブ 'trac' を提供しています。 |
28 | | |
29 | | 例: |
30 | | {{{ |
31 | | {{{ |
32 | | #!rst |
33 | | This is a reference to |a ticket| |
34 | | |
35 | | .. |a ticket| trac:: #42 |
36 | | }}} |
37 | | }}} |
38 | | |
39 | | ''trac'' ディレクティブのすべての使用例の一覧は、 WikiRestructuredTextLinks を見てください。 |
40 | | |
41 | | |
42 | | * Trac は RST で TracLinks を簡単に作成できるように、 '':trac:'' という名前 (naming scheme) を予約しています。 |
43 | | |
44 | | 例: |
45 | | {{{ |
46 | | {{{ |
47 | | #!rst |
48 | | This is a reference to ticket `#12`:trac: |
49 | | |
50 | | To learn how to use Trac, see `TracGuide`:trac: |
51 | | }}} |
52 | | }}} |
53 | | |
54 | | === reStructuredText におけるシンタックスハイライト === #SyntaxhighlightinginreStructuredText |
55 | | |
56 | | 同様に、 RST において TracSyntaxColoring を行なうディレクティブがあります。 |
57 | | ディレクティブは code-block と呼ばれます。 |
58 | | |
59 | | 例 |
60 | | |
61 | | {{{ |
62 | | {{{ |
63 | | #!rst |
64 | | |
65 | | .. code-block:: python |
66 | | |
67 | | class Test: |
68 | | |
69 | | def TestFunction(self): |
70 | | pass |
71 | | |
72 | | }}} |
73 | | }}} |
74 | | |
75 | | 上記の例は以下のように見えます。 |
76 | | |
77 | | {{{ |
78 | | #!rst |
79 | | |
80 | | .. code-block:: python |
81 | | |
82 | | class Test: |
83 | | |
84 | | def TestFunction(self): |
85 | | pass |
86 | | |
87 | | }}} |
88 | | |
89 | | === reStructuredText の中における Wiki Macros === #WikiMacrosinreStructuredText |
90 | | |
91 | | [WikiMacros Wiki マクロ] を ReST の中で使用するには、 code-block のようなシンタックスハイライトと同様のディレクティブを使用します。 |
92 | | 動作させるためには [http://trac.edgewall.org/ticket/801 #801] のパッチ適用をした Trac を使用しなければなりません。 |
93 | | |
94 | | === Wiki Macros の例 === #WikiMacroExample |
95 | | |
96 | | {{{ |
97 | | {{{ |
98 | | #!rst |
99 | | |
100 | | .. code-block:: RecentChanges |
101 | | |
102 | | Trac,3 |
103 | | |
104 | | }}} |
105 | | }}} |
106 | | |
107 | | この結果は以下のようになります: |
108 | | |
109 | | [[RecentChanges(Trac,3)]] |
110 | | |
111 | | より簡素な構文でも Wiki マクロを利用できます: |
112 | | |
113 | | {{{ |
114 | | {{{ |
115 | | #!rst |
116 | | |
117 | | :code-block:`RecentChanges:Trac,3` |
118 | | }}} |
119 | | }}} |
120 | | |
121 | | === より大きい ReST の例 === #BiggerReSTExample |
122 | | この例のように書くと、とても分かりやすくなります: |
| 23 | == Using RST in Trac == |
| 24 | To 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 | |
| 75 | There is a directive for doing TracSyntaxColoring in RST as well. The directive is called |
| 76 | code-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 | }}} |
| 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 === |
| 158 | The example below should be mostly self-explanatory: |
| 159 | |
| 160 | ||= Wiki Markup ||= Display || |
| 161 | {{{#!td |