WikiRestructuredText

= 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 text/x-rst as value for the Subversion property svn:mime-type. 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 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.

=== 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 trac:: to allow TracLinks from within RST text. ||= Wiki Markup ||= Display || {{{#!td {{{ {{{ #!rst This is a reference to |a ticket|

  .. |a ticket| trac:: #42 }}} }}} }}} {{{#!td {{{ #!rst This is a reference to |a ticket|

  .. |a ticket| trac:: #42 }}} }}}

• Trac allows an even easier way of creating TracLinks in RST, using the custom :trac: role. ||= Wiki Markup ||= Display || {{{#!td {{{ {{{ #!rst This is a reference to ticket #12:trac:

  To learn how to use Trac, see TracGuide:trac: }}} }}} }}} {{{#!td {{{ #!rst This is a reference to ticket #12:trac:

  To learn how to use Trac, see TracGuide:trac: }}} }}}

For a complete example of all uses of the :trac: 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

||= Wiki Markup ||= Display || {{{#!td {{{ {{{ #!rst

.. code-block:: python

 class Test:

     def TestFunction(self):
         pass

}}} }}} }}} {{{#!td {{{ #!rst

.. code-block:: python

 class Test:

     def TestFunction(self):
         pass

}}} }}} Note the need to indent the code at least one character after the .. code-block directive.

=== 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 Markup ||= Display || {{{#!td {{{ {{{ #!rst

.. code-block:: RecentChanges

 Trac,3

}}} }}} }}} {{{#!td {{{ #!rst

.. code-block:: RecentChanges

 Trac,3

}}} }}}

Or a more concise Wiki Macro like syntax is also available, using the :code-block: role:

||= Wiki Markup ||= Display || {{{#!td {{{ {{{ #!rst

:code-block:RecentChanges:Trac,3 }}} }}} }}} {{{#!td {{{ #!rst

:code-block:RecentChanges:Trac,3 }}} }}}

=== Bigger RST Example === The example below should be mostly self-explanatory:

||= Wiki Markup ||= Display || {{{#!td {{{ #!html

{{{
#!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 `#42`:trac:.

.. _webpage: http://docutils.sourceforge.net/rst.html
}}}

}}} }}} {{{#!td {{{ #!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 #42:trac:.

.. _webpage: http://docutils.sourceforge.net/rst.html }}} }}}

---

See also: WikiRestructuredTextLinks, WikiProcessors, WikiFormatting