Changes between Initial Version and Version 1 of WikiRestructuredText


Ignore:
Timestamp:
08/07/15 22:11:27 (4 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WikiRestructuredText

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