Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Changes between Version 4 and Version 5 of WikiRestructuredText


Ignore:
Timestamp:
Mar 18, 2017, 3:45:33 PM (8 years ago)
Author:
trac
Comment:

—

Legend:

Unmodified
Added
Removed
Modified

  • WikiRestructuredText

    v4 v5  
    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 }}}
     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.
    85105
    86106=== Wiki Macros in reStructuredText ===
    87107
    88 For doing [WikiMacros Wiki Macros] in ReST you use the same directive as for syntax highlighting i.e
    89 code-block. To work you must use a version of trac that has #801 applied.
    90 
    91 === Wiki Macro Example ===
    92 
    93 {{{
    94 {{{
    95 #!rst
    96 
    97 .. code-block:: RecentChanges
    98 
    99    Trac,3
    100 
    101 }}}
    102 }}}
    103 
    104 Will result in the below:
    105 
    106      [[RecentChanges(Trac,3)]]
    107 
    108 Or a more concise Wiki Macro like syntax is also available:
    109 
    110 {{{
    111 {{{
    112 #!rst
    113 
    114 :code-block:`RecentChanges:Trac,3`
    115 }}}
    116 }}}
    117 
    118 === Bigger ReST Example ===
    119 The example below should be mostly self-explanatory:
     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
    120159{{{
    121160#!html
    … …  
    147186}}}</pre>
    148187}}}
    149 
    150 
    151 Results in:
     188}}}
     189{{{#!td
    152190{{{
    153191#!rst
    … …  
    176214.. _webpage: http://docutils.sourceforge.net/rst.html
    177215}}}
    178 
     216}}}
    179217
    180218----