Edgewall Software

Changes between Initial Version and Version 34 of WikiRestructuredText


Ignore:
Timestamp:
(multiple changes)
Author:
(multiple changes)
Comment:
(multiple changes)

Legend:

Unmodified
Added
Removed
Modified
  • WikiRestructuredText

    v1 v34  
     1= reStructuredText Support in Trac
     2
     3== Introduction
     4
     5[[TranslatedPages]]
     6
     7Trac supports [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html reStructuredText (RST)] as an alternative to wiki markup where WikiFormatting is used.
     8
     9From the reStucturedText webpage:
     10 "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."
     11
     12If 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:branches/1.2-stable/INSTALL.rst this example].
     13
     14The 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.
     15
     16=== Requirements
     17
     18To 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].
     19
     20=== More information on RST
     21
     22 * [http://docutils.sourceforge.net/rst.html reStructuredText Website]
     23 * [http://docutils.sourceforge.net/docs/rst/quickref.html RST Quick Reference]
     24
     25== Using RST in Trac
     26
     27To specify that a block of text should be parsed using RST, use the ''rst'' processor.
     28
     29=== TracLinks in reStructuredText
     30
     31 * Trac provides a custom RST directive `trac::` to allow TracLinks from within RST text.
     32   ||= Wiki Markup ||= Display ||
     33   {{{#!td
     34     {{{
     35     {{{#!rst
     36     This is a reference to |a ticket|
     37
     38     .. |a ticket| trac:: #42
     39     }}}
     40     }}}
     41   }}}
     42   {{{#!td
     43     {{{#!rst
     44     This is a reference to |a ticket|
     45
     46     .. |a ticket| trac:: #42
     47     }}}
     48   }}}
     49
     50 * You can also use the custom `:trac:` role to create TracLinks in RST.
     51   ||= Wiki Markup ||= Display ||
     52   {{{#!td
     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     {{{#!rst
     63     This is a reference to ticket `#12`:trac:
     64
     65     To learn how to use Trac, see `TracGuide`:trac:
     66     }}}
     67   }}}
     68
     69 For a complete example of all uses of the `:trac:` role, see WikiRestructuredTextLinks.
     70
     71=== Syntax highlighting in reStructuredText
     72
     73There is a directive for doing TracSyntaxColoring in RST as well. The directive is called code-block:
     74
     75||= Wiki Markup ||= Display ||
     76{{{#!td
     77  {{{
     78  {{{#!rst
     79
     80  .. code-block:: python
     81
     82     class Test:
     83
     84         def TestFunction(self):
     85             pass
     86
     87  }}}
     88  }}}
     89}}}
     90{{{#!td
     91  {{{#!rst
     92
     93  .. code-block:: python
     94
     95     class Test:
     96
     97         def TestFunction(self):
     98             pass
     99
     100  }}}
     101}}}
     102Note the need to indent the code at least one character after the `.. code-block` directive.
     103
     104=== Wiki Macros in reStructuredText
     105
     106To enable [WikiMacros Wiki Macros] in RST, you use the same `code-block` directive as for syntax highlighting:
     107
     108||= Wiki Markup ||= Display ||
     109{{{#!td
     110  {{{
     111  {{{#!rst
     112
     113  .. code-block:: RecentChanges
     114
     115     Trac,3
     116
     117  }}}
     118  }}}
     119}}}
     120{{{#!td
     121  {{{#!rst
     122
     123  .. code-block:: RecentChanges
     124
     125     Trac,3
     126
     127  }}}
     128}}}
     129
     130Or use the `:code-block:` role for a more concise Wiki Macro-like syntax:
     131
     132||= Wiki Markup ||= Display ||
     133{{{#!td
     134  {{{
     135  {{{
     136  #!rst
     137
     138  :code-block:`RecentChanges:Trac,3`
     139  }}}
     140  }}}
     141}}}
     142{{{#!td
     143  {{{#!rst
     144
     145  :code-block:`RecentChanges:Trac,3`
     146  }}}
     147}}}
     148
     149=== Bigger RST Example
     150
     151The example below should be self-explanatory:
     152
     153||= Wiki Markup ||= Display ||
     154{{{#!td
     155{{{#!html
     156<pre class="wiki">{{{#!rst
     157FooBar Header
     158=============
     159reStructuredText is **nice**. It has its own webpage_.
     160
     161A table:
     162
     163=====  =====  ======
     164   Inputs     Output
     165------------  ------
     166  A      B    A or B
     167=====  =====  ======
     168False  False  False
     169True   False  True
     170False  True   True
     171True   True   True
     172=====  =====  ======
     173
     174RST TracLinks
     175-------------
     176
     177See also ticket `#42`:trac:.
     178
     179.. _webpage: http://docutils.sourceforge.net/rst.html
     180}}}</pre>
     181}}}
     182}}}
     183{{{#!td
     184{{{#!rst
     185FooBar Header
     186=============
     187reStructuredText is **nice**. It has its own webpage_.
     188
     189A table:
     190
     191=====  =====  ======
     192   Inputs     Output
     193------------  ------
     194  A      B    A or B
     195=====  =====  ======
     196False  False  False
     197True   False  True
     198False  True   True
     199True   True   True
     200=====  =====  ======
     201
     202RST TracLinks
     203-------------
     204
     205See also ticket `#42`:trac:.
     206
     207.. _webpage: http://docutils.sourceforge.net/rst.html
     208}}}
     209}}}
     210
     211----
     212See also: WikiRestructuredTextLinks, WikiProcessors, WikiFormatting