Changes between Version 1 and Version 2 of WikiRestructuredText


Ignore:
Timestamp:
10/23/15 08:16:58 (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].
     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.
    1114
    1215=== More information on RST ===
    … …  
    2225=== TracLinks in reStructuredText ===
    2326
    24  * Trac provides a custom RST reference-directive 'trac' to allow TracLinks from within RST text.
    25 
    26  Example:
    27  {{{
    28  {{{
    29  #!rst
    30  This is a reference to |a ticket|
    31 
    32  .. |a ticket| trac:: #42
    33  }}}
    34  }}}
    35 
    36  For a complete example of all uses of the ''trac''-directive, please see WikiRestructuredTextLinks.
    37 
    38 
    39  * Trac allows an even easier way of creating TracLinks in RST, using the custom '':trac:'' link naming scheme.
    40 
    41  Example:
    42  {{{
    43  {{{
    44  #!rst
    45  This is a reference to ticket `#12`:trac:
    46 
    47  To learn how to use Trac, see `TracGuide`:trac:
    48  }}}
    49  }}}
     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.
    5070
    5171=== Syntax highlighting in reStructuredText ===
    5272
    53 There is a directive for doing TracSyntaxColoring in ReST as well. The directive is called
    54 code-block
    55 
    56 Example
    57 
    58 {{{
    59 {{{
    60 #!rst
    61 
    62 .. code-block:: python
    63 
    64  class Test:
    65 
    66     def TestFunction(self):
    67         pass
    68 
    69 }}}
    70 }}}
    71 
    72 Will result in the below.
    73 
    74 {{{
    75 #!rst
    76 
    77 .. code-block:: python
    78 
    79  class Test:
    80 
    81     def TestFunction(self):
    82         pass
    83 
    84 }}}
    85 
    86 === WikiMacros in reStructuredText ===
    87 
    88 For doing WikiMacros in ReST you use the same directive as for syntax highlightning i.e
    89 code-block. To work you must use a version of trac that has #801 applied.
    90 
    91 === WikiMacro Example ===
    92 
    93 {{{
    94 {{{
    95 #!rst
    96 
    97 .. code-block:: HelloWorld
    98  
    99    Something I wanted to say
    100 
    101 
    102 }}}
    103 }}}
    104 
    105 Will result in the below.
    106 
    107 [[HelloWorld(Something I wanted to say)]]
    108 
    109 
    110 === Bigger ReST Example ===
    111 The example below should be mostly self-explanatory:
     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
    112159{{{
    113160#!html
    … …  
    139186}}}</pre>
    140187}}}
    141 
    142 
    143 Results in:
     188}}}
     189{{{#!td
    144190{{{
    145191#!rst
    … …  
    168214.. _webpage: http://docutils.sourceforge.net/rst.html
    169215}}}
    170 
     216}}}
    171217
    172218----