Changes between Version 2 and Version 3 of WikiRestructuredText


Ignore:
Timestamp:
04/22/15 15:13:21 (10 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiRestructuredText

    v2 v3  
    11= reStructuredText Support in Trac =
    22
    3 Trac supports using ''reStructuredText'' (RST) as an alternative to wiki markup in any context WikiFormatting is used.
     3Trac supports [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html reStructuredText (RST)] as an alternative to wiki markup where WikiFormatting is used.
    44
    55From the reStucturedText webpage:
    66 "''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. ''"
    77
    8 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].
     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].
    99
    1010=== Requirements ===
    11 Note that to activate RST support in Trac, the python docutils package must be installed.
    12 If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website].
    13 
    14 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.
     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.
    1514
    1615=== More information on RST ===
    … …  
    2726
    2827 * Trac provides a custom RST directive `trac::` to allow TracLinks from within RST text.
    29 
    30  Example:
    31  {{{
    32  {{{
    33  #!rst
    34  This is a reference to |a ticket|
    35 
    36  .. |a ticket| trac:: #42
    37  }}}
    38  }}}
     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   }}}
    3947
    4048 * Trac allows an even easier way of creating TracLinks in RST, using the custom `:trac:` role.
    41 
    42  Example:
    43  {{{
    44  {{{
    45  #!rst
    46  This is a reference to ticket `#12`:trac:
    47 
    48  To learn how to use Trac, see `TracGuide`:trac:
    49  }}}
    50  }}}
     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   }}}
    5168
    5269 For a complete example of all uses of the `:trac:` role, please see WikiRestructuredTextLinks.
    5370
    54 
    5571=== Syntax highlighting in reStructuredText ===
    5672
    57 There is a directive for doing TracSyntaxColoring in RST as well. The directive is called
    58 code-block
    59 
    60 Example
    61 
    62 {{{
    63 {{{
    64 #!rst
    65 
    66 .. code-block:: python
    67 
    68  class Test:
    69 
    70     def TestFunction(self):
    71         pass
    72 
    73 }}}
    74 }}}
    75 
    76 Will result in the below.
    77 
    78 {{{
    79 #!rst
    80 
    81 .. code-block:: python
    82 
    83  class Test:
    84 
    85     def TestFunction(self):
    86         pass
    87 
    88 }}}
     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.
    89105
    90106=== Wiki Macros in reStructuredText ===
    91107
    92 For doing [WikiMacros Wiki Macros] in RST you use the same directive as for syntax highlighting i.e
    93 code-block. To work you must use a version of trac that has [trac:ticket:801 #801] applied.
    94 
    95 === Wiki Macro Example ===
    96 
    97 {{{
    98 {{{
    99 #!rst
    100 
    101 .. code-block:: RecentChanges
    102 
    103    Trac,3
    104 
    105 }}}
    106 }}}
    107 
    108 Will result in the below:
    109 
    110      [[RecentChanges(Trac,3)]]
    111 
    112 Or a more concise Wiki Macro like syntax is also available:
    113 
    114 {{{
    115 {{{
    116 #!rst
    117 
    118 :code-block:`RecentChanges:Trac,3`
    119 }}}
     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  }}}
    120152}}}
    121153
    122154=== Bigger RST Example ===
    123 The example below should be mostly self-explanatory:
     155The example below should be self-explanatory:
     156
     157||= Wiki Markup ||= Display ||
     158{{{#!td
    124159{{{
    125160#!html
    … …  
    151186}}}</pre>
    152187}}}
    153 
    154 
    155 Results in:
     188}}}
     189{{{#!td
    156190{{{
    157191#!rst
    … …  
    180214.. _webpage: http://docutils.sourceforge.net/rst.html
    181215}}}
    182 
     216}}}
    183217
    184218----