Changes between Version 2 and Version 3 of WikiRestructuredText


Ignore:
Timestamp:
Jan 30, 2018 2:16:51 PM (7 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiRestructuredText

    v2 v3  
    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 === 
    17  
    18  * reStructuredText Website -- http://docutils.sourceforge.net/rst.html 
    19  * RST Quick Reference -- http://docutils.sourceforge.net/docs/rst/quickref.html 
    20  
    21 ---- 
    22  
    23 == Using RST in Trac == 
     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`, or add the extension `rst` to the filename. See [trac:source:/trunk/INSTALL.rst this example]. 
     12 
     13The examples will only be rendered as reStructuredText if docutils is installed. If Pygments is installed but docutils is not installed, the examples will be syntax-highlighted rather than rendered as reStructuredText. 
     14 
     15=== Requirements 
     16 
     17To activate RST support in Trac, install the python docutils package with the command `easy_install docutils`, or through your operating system package manager. If not already available on your operating system, you can download it from [https://pypi.python.org/pypi/docutils PyPI]. 
     18 
     19=== More information on RST 
     20 
     21 * [http://docutils.sourceforge.net/rst.html reStructuredText Website] 
     22 * [http://docutils.sourceforge.net/docs/rst/quickref.html RST Quick Reference] 
     23 
     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. 
    … …  
    3032   {{{#!td 
    3133     {{{ 
     34     {{{#!rst 
     35     This is a reference to |a ticket| 
     36 
     37     .. |a ticket| trac:: #42 
     38     }}} 
     39     }}} 
     40   }}} 
     41   {{{#!td 
     42     {{{#!rst 
     43     This is a reference to |a ticket| 
     44 
     45     .. |a ticket| trac:: #42 
     46     }}} 
     47   }}} 
     48 
     49 * You can also use the custom `:trac:` role to create TracLinks in RST. 
     50   ||= Wiki Markup ||= Display || 
     51   {{{#!td 
    3252     {{{ 
    33      #!rst 
    34      This is a reference to |a ticket| 
    35  
    36      .. |a ticket| trac:: #42 
    37      }}} 
    38      }}} 
    39    }}} 
    40    {{{#!td 
    41      {{{ 
    42      #!rst 
    43      This is a reference to |a ticket| 
    44  
    45      .. |a ticket| trac:: #42 
    46      }}} 
    47    }}} 
    48  
    49  * Trac allows an even easier way of creating TracLinks in RST, using the custom `:trac:` role. 
    50    ||= Wiki Markup ||= Display || 
    51    {{{#!td 
    52      {{{ 
    53      {{{ 
    54      #!rst 
     53     {{{#!rst 
    5554     This is a reference to ticket `#12`:trac: 
    5655 
    … …  
    6059   }}} 
    6160   {{{#!td 
    62      {{{ 
    63      #!rst 
     61     {{{#!rst 
    6462     This is a reference to ticket `#12`:trac: 
    6563 
    … …  
    6866   }}} 
    6967 
    70  For a complete example of all uses of the `:trac:` role, please see WikiRestructuredTextLinks.  
    71  
    72  
    73 === Syntax highlighting in reStructuredText === 
    74  
    75 There is a directive for doing TracSyntaxColoring in RST as well. The directive is called 
    76 code-block 
    77  
    78 ||= Wiki Markup ||= Display || 
    79 {{{#!td 
    80   {{{ 
    81   {{{ 
    82   #!rst 
     68 For a complete example of all uses of the `:trac:` role, see WikiRestructuredTextLinks.  
     69 
     70=== Syntax highlighting in reStructuredText 
     71 
     72There is a directive for doing TracSyntaxColoring in RST as well. The directive is called code-block: 
     73 
     74||= Wiki Markup ||= Display || 
     75{{{#!td 
     76  {{{ 
     77  {{{#!rst 
    8378 
    8479  .. code-block:: python 
    … …  
    9388}}} 
    9489{{{#!td 
    95   {{{ 
    96   #!rst 
     90  {{{#!rst 
    9791 
    9892  .. code-block:: python 
    … …  
    107101Note the need to indent the code at least one character after the `.. code-block` directive. 
    108102 
    109 === Wiki Macros in reStructuredText === 
    110  
    111 For doing [WikiMacros Wiki Macros] in RST you use the same directive as for syntax highlighting i.e code-block. 
     103=== Wiki Macros in reStructuredText 
     104 
     105To enable [WikiMacros Wiki Macros] in RST, you use the same `code-block` directive as for syntax highlighting: 
     106 
     107||= Wiki Markup ||= Display || 
     108{{{#!td 
     109  {{{ 
     110  {{{#!rst 
     111 
     112  .. code-block:: RecentChanges 
     113 
     114     Trac,3 
     115 
     116  }}} 
     117  }}} 
     118}}} 
     119{{{#!td 
     120  {{{#!rst 
     121 
     122  .. code-block:: RecentChanges 
     123 
     124     Trac,3 
     125 
     126  }}} 
     127}}} 
     128 
     129Or use the `:code-block:` role for a more concise Wiki Macro-like syntax: 
    112130 
    113131||= Wiki Markup ||= Display || 
    … …  
    117135  #!rst 
    118136 
    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  
    137 Or 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  
    145137  :code-block:`RecentChanges:Trac,3` 
    146138  }}} 
    … …  
    148140}}} 
    149141{{{#!td 
    150   {{{ 
    151   #!rst 
     142  {{{#!rst 
    152143 
    153144  :code-block:`RecentChanges:Trac,3` 
    … …  
    155146}}} 
    156147 
    157 === Bigger RST Example === 
    158 The example below should be mostly self-explanatory: 
    159  
    160 ||= Wiki Markup ||= Display || 
    161 {{{#!td 
    162 {{{ 
    163 #!html 
    164 <pre class="wiki">{{{ 
    165 #!rst 
     148=== Bigger RST Example 
     149 
     150The example below should be self-explanatory: 
     151 
     152||= Wiki Markup ||= Display || 
     153{{{#!td 
     154{{{#!html 
     155<pre class="wiki">{{{#!rst 
    166156FooBar Header 
    167157============= 
    … …  
    191181}}} 
    192182{{{#!td 
    193 {{{ 
    194 #!rst 
     183{{{#!rst 
    195184FooBar Header 
    196185=============