Maintenance script: Created page with " == reStructuredText Support in Trac == Trac supports using ''reStructuredText'' (RST) as an alternative to wiki markup in any context WikiFormatting is used. From the reStu..."

2015-08-26T12:29:30Z

Created page with " == reStructuredText Support in Trac == Trac supports using ''reStructuredText'' (RST) as an alternative to wiki markup in any context WikiFormatting is used. From the reStu..."

New page

== reStructuredText Support in Trac ==

Trac supports using ''reStructuredText'' (RST) as an alternative to wiki markup in any context 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 be displayed as reStructuredText in Trac's source browser, set <tt>text/x-rst</tt> as value for the Subversion property <tt>svn:mime-type</tt>. See [trac:source:/trunk/INSTALL this example].

==== Requirements ====
Note that to activate RST support in Trac, the python docutils package must be installed.
If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website].

Install docutils using <tt>easy_install docutils</tt>. Do not use the package manager of your OS (e.g. <tt>apt-get install python-docutils</tt>), because Trac will not find docutils then.

==== More information on RST ====

*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.

==== TracLinks in reStructuredText ====

*Trac provides a custom RST directive <tt>trac::</tt> to allow TracLinks from within RST text.

Example:
<pre>
<pre>
#rst
This is a reference to |a ticket|

.. |a ticket| trac:: #42
</pre>
</pre>

*Trac allows an even easier way of creating TracLinks in RST, using the custom <tt>:trac:</tt> role.

Example:
<pre>
<pre>
#rst
This is a reference to ticket <tt>#12</tt>:trac:

To learn how to use Trac, see <tt>TracGuide</tt>:trac:
</pre>
</pre>

For a complete example of all uses of the <tt>:trac:</tt> role, please see WikiRestructuredTextLinks.

==== Syntax highlighting in reStructuredText ====

There is a directive for doing TracSyntaxColoring in RST as well. The directive is called
code-block

Example

<pre>
<pre>
#rst

.. code-block:: python

class Test:

def TestFunction(self):
pass

</pre>
</pre>

Will result in the below.

<pre>
#rst

.. code-block:: python

class Test:

def TestFunction(self):
pass

</pre>

==== Wiki Macros in reStructuredText ====

For doing [WikiMacros Wiki Macros] in RST you use the same directive as for syntax highlighting i.e code-block.

==== Wiki Macro Example ====

<pre>
<pre>
#rst

.. code-block:: RecentChanges

Trac,3

</pre>
</pre>

Will result in the below:

[[RecentChanges(Trac,3)]]

Or a more concise Wiki Macro like syntax is also available:

<pre>
<pre>
#rst

:code-block:<tt>RecentChanges:Trac,3</tt>
</pre>
</pre>

==== Bigger RST Example ====
The example below should be mostly self-explanatory:
<pre>
#html
<pre class="wiki"><pre>
#rst
FooBar Header
=============
reStructuredText is **nice**. It has its own webpage_.

A table:

===== ===== ======
Inputs Output
------------ ------
A B A or B
===== ===== ======
False False False
True False True
False True True
True True True
===== ===== ======

RST TracLinks
-------------

See also ticket <tt>#42</tt>:trac:.

.. _webpage: http://docutils.sourceforge.net/rst.html
</pre></pre>
</pre>

Results in:
<pre>
#rst
FooBar Header
=============
reStructuredText is **nice**. It has its own webpage_.

A table:

===== ===== ======
Inputs Output
------------ ------
A B A or B
===== ===== ======
False False False
True False True
False True True
True True True
===== ===== ======

RST TracLinks
-------------

See also ticket <tt>#42</tt>:trac:.

.. _webpage: http://docutils.sourceforge.net/rst.html
</pre>

----
See also: WikiRestructuredTextLinks, WikiProcessors, WikiFormatting

{{TracNotice|{{PAGENAME}}}}

WikiRestructuredText - Revision history

Maintenance script: Created page with " == reStructuredText Support in Trac == Trac supports using ''reStructuredText'' (RST) as an alternative to wiki markup in any context WikiFormatting is used. From the reStu..."