Changes between Version 3 and Version 4 of WikiRestructuredText


Ignore:
Timestamp:
Apr 24, 2017, 10:36:12 AM (9 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiRestructuredText

    v3 v4  
    1 = reStructuredText Support in Trac =
    2 
    3 Trac supports using ''reStructuredText'' (RST) as an alternative to wiki markup in any context WikiFormatting is used.
     1= reStructuredText Support in Trac
     2
     3== Introduction
     4
     5
     6Trac supports [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html reStructuredText (RST)] as an alternative to wiki markup where WikiFormatting is used.
    47
    58From 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 
    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].
    9 
    10 === 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.
    15 
    16 === More information on RST ===
     9 "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."
     10
     11If 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].
     12
     13=== Requirements
     14
     15To 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].
     16
     17Do not use the package manager of your OS, eg `apt-get install python-docutils`, because Trac will not find docutils then.
     18
     19=== More information on RST
    1720
    1821 * reStructuredText Website -- http://docutils.sourceforge.net/rst.html
    1922 * RST Quick Reference -- http://docutils.sourceforge.net/docs/rst/quickref.html
    2023
    21 ----
    22 
    23 == Using RST in Trac ==
     24== Using RST in Trac
     25
    2426To specify that a block of text should be parsed using RST, use the ''rst'' processor.
    2527
    26 === TracLinks in reStructuredText ===
     28=== TracLinks in reStructuredText
    2729
    2830 * 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  }}}
     31   ||= Wiki Markup ||= Display ||
     32   {{{#!td
     33     {{{
     34     {{{
     35     #!rst
     36     This is a reference to |a ticket|
     37
     38     .. |a ticket| trac:: #42
     39     }}}
     40     }}}
     41   }}}
     42   {{{#!td
     43     {{{
     44     #!rst
     45     This is a reference to |a ticket|
     46
     47     .. |a ticket| trac:: #42
     48     }}}
     49   }}}
    3950
    4051 * 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  }}}
     52   ||= Wiki Markup ||= Display ||
     53   {{{#!td
     54     {{{
     55     {{{
     56     #!rst
     57     This is a reference to ticket `#12`:trac:
     58
     59     To learn how to use Trac, see `TracGuide`:trac:
     60     }}}
     61     }}}
     62   }}}
     63   {{{#!td
     64     {{{
     65     #!rst
     66     This is a reference to ticket `#12`:trac:
     67
     68     To learn how to use Trac, see `TracGuide`:trac:
     69     }}}
     70   }}}
    5171
    5272 For a complete example of all uses of the `:trac:` role, please see WikiRestructuredTextLinks.
    5373
    54 
    55 === Syntax highlighting in reStructuredText ===
    56 
    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 }}}
    89 
    90 === Wiki Macros in reStructuredText ===
    91 
    92 For doing [WikiMacros Wiki Macros] in RST you use the same directive as for syntax highlighting i.e code-block.
    93 
    94 === Wiki Macro Example ===
    95 
    96 {{{
    97 {{{
    98 #!rst
    99 
    100 .. code-block:: RecentChanges
    101 
    102    Trac,3
    103 
    104 }}}
    105 }}}
    106 
    107 Will result in the below:
    108 
    109      [[RecentChanges(Trac,3)]]
    110 
    111 Or a more concise Wiki Macro like syntax is also available:
    112 
    113 {{{
    114 {{{
    115 #!rst
    116 
    117 :code-block:`RecentChanges:Trac,3`
    118 }}}
    119 }}}
    120 
    121 === Bigger RST Example ===
    122 The example below should be mostly self-explanatory:
     74=== Syntax highlighting in reStructuredText
     75
     76There is a directive for doing TracSyntaxColoring in RST as well. The directive is called code-block:
     77
     78||= Wiki Markup ||= Display ||
     79{{{#!td
     80  {{{
     81  {{{
     82  #!rst
     83
     84  .. code-block:: python
     85
     86     class Test:
     87
     88         def TestFunction(self):
     89             pass
     90 
     91  }}}
     92  }}}
     93}}}
     94{{{#!td
     95  {{{
     96  #!rst
     97
     98  .. code-block:: python
     99
     100     class Test:
     101
     102         def TestFunction(self):
     103             pass
     104
     105  }}}
     106}}}
     107Note the need to indent the code at least one character after the `.. code-block` directive.
     108
     109=== Wiki Macros in reStructuredText
     110
     111To enable [WikiMacros Wiki Macros] in RST, you use the same directive as for syntax highlighting, ie code-block:
     112
     113||= Wiki Markup ||= Display ||
     114{{{#!td
     115  {{{
     116  {{{
     117  #!rst
     118
     119  .. code-block:: RecentChanges
     120
     121     Trac,3
     122
     123  }}}
     124  }}}
     125}}}
     126{{{#!td
     127  {{{
     128  #!rst
     129
     130  .. code-block:: RecentChanges
     131
     132     Trac,3
     133
     134  }}}
     135}}}
     136
     137Or a more concise Wiki Macro-like syntax is also available, using the `:code-block:` role:
     138
     139||= Wiki Markup ||= Display ||
     140{{{#!td
     141  {{{
     142  {{{
     143  #!rst
     144
     145  :code-block:`RecentChanges:Trac,3`
     146  }}}
     147  }}}
     148}}}
     149{{{#!td
     150  {{{
     151  #!rst
     152
     153  :code-block:`RecentChanges:Trac,3`
     154  }}}
     155}}}
     156
     157=== Bigger RST Example
     158
     159The example below should be self-explanatory:
     160
     161||= Wiki Markup ||= Display ||
     162{{{#!td
    123163{{{
    124164#!html
    … …  
    150190}}}</pre>
    151191}}}
    152 
    153 
    154 Results in:
     192}}}
     193{{{#!td
    155194{{{
    156195#!rst
    … …  
    179218.. _webpage: http://docutils.sourceforge.net/rst.html
    180219}}}
    181 
     220}}}
    182221
    183222----