... | ... | @@ -3,33 +3,33 @@ |
|
|
== Introduction
|
|
|
|
|
|
|
|
|
Trac supports [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html reStructuredText (RST)] as an alternative to wiki markup where WikiFormatting is used.
|
|
|
Trac supports [reStructuredText (RST)](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html) as an alternative to wiki markup where WikiFormatting is used.
|
|
|
|
|
|
From the reStucturedText webpage:
|
|
|
"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."
|
|
|
|
|
|
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`, or add the extension `rst` to the filename. See [trac:source:/trunk/INSTALL.rst this example].
|
|
|
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`, or add the extension `rst` to the filename. See [trac:[INSTALL.rst](INSTALL.rst) this example].
|
|
|
|
|
|
The examples will only be rendered as reStructuredText if docutils is installed. If Pygments is installed but docutils is not installed, the examples will be syntax-highlighted rather than rendered as reStructuredText.
|
|
|
|
|
|
=== Requirements
|
|
|
|
|
|
To activate RST support in Trac, install the python docutils package with the command `easy_install docutils`, or through your operating system package manager. If not already available on your operating system, you can download it from [https://pypi.python.org/pypi/docutils PyPI].
|
|
|
To activate RST support in Trac, install the python docutils package with the command `easy_install docutils`, or through your operating system package manager. If not already available on your operating system, you can download it from [PyPI](https://pypi.python.org/pypi/docutils).
|
|
|
|
|
|
=== More information on RST
|
|
|
|
|
|
* [http://docutils.sourceforge.net/rst.html reStructuredText Website]
|
|
|
* [http://docutils.sourceforge.net/docs/rst/quickref.html RST Quick Reference]
|
|
|
* [reStructuredText Website](http://docutils.sourceforge.net/rst.html)
|
|
|
* [RST Quick Reference](http://docutils.sourceforge.net/docs/rst/quickref.html)
|
|
|
|
|
|
== Using RST in Trac
|
|
|
|
|
|
To specify that a block of text should be parsed using RST, use the ''rst'' processor.
|
|
|
To specify that a block of text should be parsed using RST, use the _rst_ processor.
|
|
|
|
|
|
=== TracLinks in reStructuredText
|
|
|
|
|
|
* Trac provides a custom RST directive `trac::` to allow TracLinks from within RST text.
|
|
|
||= Wiki Markup ||= Display ||
|
|
|
{{{#!td
|
|
|
```
|
|
|
{{{
|
|
|
{{{#!rst
|
|
|
This is a reference to |a ticket|
|
... | ... | @@ -71,7 +71,8 @@ To specify that a block of text should be parsed using RST, use the ''rst'' proc |
|
|
|
|
|
There is a directive for doing TracSyntaxColoring in RST as well. The directive is called code-block:
|
|
|
|
|
|
||= Wiki Markup ||= Display ||
|
|
|
|= Wiki Markup |= Display |
|
|
|
|--------------|----------|
|
|
|
{{{#!td
|
|
|
{{{
|
|
|
{{{#!rst
|
... | ... | @@ -85,8 +86,8 @@ There is a directive for doing TracSyntaxColoring in RST as well. The directive |
|
|
|
|
|
}}}
|
|
|
}}}
|
|
|
}}}
|
|
|
{{{#!td
|
|
|
```
|
|
|
```
|
|
|
{{{#!rst
|
|
|
|
|
|
.. code-block:: python
|
... | ... | @@ -97,15 +98,16 @@ There is a directive for doing TracSyntaxColoring in RST as well. The directive |
|
|
pass
|
|
|
|
|
|
}}}
|
|
|
}}}
|
|
|
```
|
|
|
Note the need to indent the code at least one character after the `.. code-block` directive.
|
|
|
|
|
|
=== Wiki Macros in reStructuredText
|
|
|
|
|
|
To enable [WikiMacros Wiki Macros] in RST, you use the same `code-block` directive as for syntax highlighting:
|
|
|
|
|
|
||= Wiki Markup ||= Display ||
|
|
|
{{{#!td
|
|
|
|= Wiki Markup |= Display |
|
|
|
|--------------|----------|
|
|
|
```
|
|
|
{{{
|
|
|
{{{#!rst
|
|
|
|
... | ... | @@ -115,8 +117,8 @@ To enable [WikiMacros Wiki Macros] in RST, you use the same `code-block` directi |
|
|
|
|
|
}}}
|
|
|
}}}
|
|
|
}}}
|
|
|
{{{#!td
|
|
|
```
|
|
|
```
|
|
|
{{{#!rst
|
|
|
|
|
|
.. code-block:: RecentChanges
|
... | ... | @@ -124,12 +126,13 @@ To enable [WikiMacros Wiki Macros] in RST, you use the same `code-block` directi |
|
|
Trac,3
|
|
|
|
|
|
}}}
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
Or use the `:code-block:` role for a more concise Wiki Macro-like syntax:
|
|
|
|
|
|
||= Wiki Markup ||= Display ||
|
|
|
{{{#!td
|
|
|
|= Wiki Markup |= Display |
|
|
|
|--------------|----------|
|
|
|
```
|
|
|
{{{
|
|
|
{{{
|
|
|
#!rst
|
... | ... | @@ -137,20 +140,21 @@ Or use the `:code-block:` role for a more concise Wiki Macro-like syntax: |
|
|
:code-block:`RecentChanges:Trac,3`
|
|
|
}}}
|
|
|
}}}
|
|
|
}}}
|
|
|
{{{#!td
|
|
|
```
|
|
|
```
|
|
|
{{{#!rst
|
|
|
|
|
|
:code-block:`RecentChanges:Trac,3`
|
|
|
}}}
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
=== Bigger RST Example
|
|
|
|
|
|
The example below should be self-explanatory:
|
|
|
|
|
|
||= Wiki Markup ||= Display ||
|
|
|
{{{#!td
|
|
|
|= Wiki Markup |= Display |
|
|
|
|--------------|----------|
|
|
|
```
|
|
|
{{{#!html
|
|
|
<pre class="wiki">{{{#!rst
|
|
|
FooBar Header
|
... | ... | @@ -176,10 +180,10 @@ RST TracLinks |
|
|
See also ticket `#42`:trac:.
|
|
|
|
|
|
.. _webpage: http://docutils.sourceforge.net/rst.html
|
|
|
}}}</pre>
|
|
|
```</pre>
|
|
|
}}}
|
|
|
}}}
|
|
|
{{{#!td
|
|
|
```
|
|
|
{{{#!rst
|
|
|
FooBar Header
|
|
|
=============
|
... | ... | @@ -204,7 +208,7 @@ RST TracLinks |
|
|
See also ticket `#42`:trac:.
|
|
|
|
|
|
.. _webpage: http://docutils.sourceforge.net/rst.html
|
|
|
}}}
|
|
|
```
|
|
|
}}}
|
|
|
|
|
|
----
|
... | ... | |