Edgewall Software

Changes between Initial Version and Version 1 of 0.12/WikiRestructuredText


Ignore:
Timestamp:
Jul 16, 2012, 9:16:12 PM (7 years ago)
Author:
trac
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • 0.12/WikiRestructuredText

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