Changes between Version 1 and Version 2 of WikiRestructuredText


Ignore:
Timestamp:
03/09/15 14:12:24 (10 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiRestructuredText

    v1 v2  
    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
     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
    810=== Requirements ===
    9 Note that to activate RST support in Trac, the python docutils package must be installed.
    10 If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website].
    11 
    12 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.
    1314
    1415=== More information on RST ===
    … …  
    2526
    2627 * Trac provides a custom RST directive `trac::` to allow TracLinks from within RST text.
    27 
    28  Example:
    29  {{{
    30  {{{
    31  #!rst
    32  This is a reference to |a ticket|
    33 
    34  .. |a ticket| trac:: #42
    35  }}}
    36  }}}
     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   }}}
    3747
    3848 * Trac allows an even easier way of creating TracLinks in RST, using the custom `:trac:` role.
    39 
    40  Example:
    41  {{{
    42  {{{
    43  #!rst
    44  This is a reference to ticket `#12`:trac:
    45 
    46  To learn how to use Trac, see `TracGuide`:trac:
    47  }}}
    48  }}}
     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   }}}
    4968
    5069 For a complete example of all uses of the `:trac:` role, please see WikiRestructuredTextLinks.
    5170
    52 
    5371=== Syntax highlighting in reStructuredText ===
    5472
    55 There is a directive for doing TracSyntaxColoring in RST as well. The directive is called
    56 code-block
    57 
    58 Example
    59 
    60 {{{
    61 {{{
    62 #!rst
    63 
    64 .. code-block:: python
    65 
    66  class Test:
    67 
    68     def TestFunction(self):
    69         pass
    70 
    71 }}}
    72 }}}
    73 
    74 Will result in the below.
    75 
    76 {{{
    77 #!rst
    78 
    79 .. code-block:: python
    80 
    81  class Test:
    82 
    83     def TestFunction(self):
    84         pass
    85 
    86 }}}
     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.
    87105
    88106=== Wiki Macros in reStructuredText ===
    89107
    90 For doing [WikiMacros Wiki Macros] in RST you use the same directive as for syntax highlighting i.e
    91 code-block. To work you must use a version of trac that has [trac:ticket:801 #801] applied.
    92 
    93 === Wiki Macro Example ===
    94 
    95 {{{
    96 {{{
    97 #!rst
    98 
    99 .. code-block:: RecentChanges
    100 
    101    Trac,3
    102 
    103 }}}
    104 }}}
    105 
    106 Will result in the below:
    107 
    108      [[RecentChanges(Trac,3)]]
    109 
    110 Or a more concise Wiki Macro like syntax is also available:
    111 
    112 {{{
    113 {{{
    114 #!rst
    115 
    116 :code-block:`RecentChanges:Trac,3`
    117 }}}
     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  }}}
    118152}}}
    119153
    120154=== Bigger RST Example ===
    121 The example below should be mostly self-explanatory:
     155The example below should be self-explanatory:
     156
     157||= Wiki Markup ||= Display ||
     158{{{#!td
    122159{{{
    123160#!html
    … …  
    149186}}}</pre>
    150187}}}
    151 
    152 
    153 Results in:
     188}}}
     189{{{#!td
    154190{{{
    155191#!rst
    … …  
    178214.. _webpage: http://docutils.sourceforge.net/rst.html
    179215}}}
    180 
     216}}}
    181217
    182218----