Changes between Version 2 and Version 3 of WikiRestructuredText


Ignore:
Timestamp:
May 2, 2019, 9:45:05 AM (15 months ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WikiRestructuredText

    v2 v3  
    1 = reStructuredText Support in Trac
    2 
    3 == Introduction
    4 
     1= reStructuredText Support in Trac =
    52
    63Trac supports [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html reStructuredText (RST)] as an alternative to wiki markup where WikiFormatting is used.
    74
    85From the reStucturedText webpage:
    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 
    11 If 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 
    13 The 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 
    17 To 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 
     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
     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
     10=== Requirements ===
     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.
     14
     15=== More information on RST ===
     16
     17 * reStructuredText Website -- http://docutils.sourceforge.net/rst.html
     18 * RST Quick Reference -- http://docutils.sourceforge.net/docs/rst/quickref.html
     19
     20----
     21
     22== Using RST in Trac ==
    2623To specify that a block of text should be parsed using RST, use the ''rst'' processor.
    2724
    28 === TracLinks in reStructuredText
     25=== TracLinks in reStructuredText ===
    2926
    3027 * Trac provides a custom RST directive `trac::` to allow TracLinks from within RST text.
     
    3229   {{{#!td
    3330     {{{
    34      {{{#!rst
     31     {{{
     32     #!rst
    3533     This is a reference to |a ticket|
    3634
     
    4038   }}}
    4139   {{{#!td
    42      {{{#!rst
     40     {{{
     41     #!rst
    4342     This is a reference to |a ticket|
    4443
     
    4746   }}}
    4847
    49  * You can also use the custom `:trac:` role to create TracLinks in RST.
     48 * Trac allows an even easier way of creating TracLinks in RST, using the custom `:trac:` role.
    5049   ||= Wiki Markup ||= Display ||
    5150   {{{#!td
    5251     {{{
    53      {{{#!rst
     52     {{{
     53     #!rst
    5454     This is a reference to ticket `#12`:trac:
    5555
     
    5959   }}}
    6060   {{{#!td
    61      {{{#!rst
     61     {{{
     62     #!rst
    6263     This is a reference to ticket `#12`:trac:
    6364
     
    6667   }}}
    6768
    68  For a complete example of all uses of the `:trac:` role, see WikiRestructuredTextLinks.
    69 
    70 === Syntax highlighting in reStructuredText
     69 For a complete example of all uses of the `:trac:` role, please see WikiRestructuredTextLinks.
     70
     71=== Syntax highlighting in reStructuredText ===
    7172
    7273There is a directive for doing TracSyntaxColoring in RST as well. The directive is called code-block:
     
    7576{{{#!td
    7677  {{{
    77   {{{#!rst
     78  {{{
     79  #!rst
    7880
    7981  .. code-block:: python
     
    8890}}}
    8991{{{#!td
    90   {{{#!rst
     92  {{{
     93  #!rst
    9194
    9295  .. code-block:: python
     
    101104Note the need to indent the code at least one character after the `.. code-block` directive.
    102105
    103 === Wiki Macros in reStructuredText
    104 
    105 To 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
     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
    111115
    112116  .. code-block:: RecentChanges
     
    118122}}}
    119123{{{#!td
    120   {{{#!rst
     124  {{{
     125  #!rst
    121126
    122127  .. code-block:: RecentChanges
     
    127132}}}
    128133
    129 Or use the `:code-block:` role for a more concise Wiki Macro-like syntax:
     134Or a more concise Wiki Macro-like syntax is also available, using the `:code-block:` role:
    130135
    131136||= Wiki Markup ||= Display ||
     
    140145}}}
    141146{{{#!td
    142   {{{#!rst
     147  {{{
     148  #!rst
    143149
    144150  :code-block:`RecentChanges:Trac,3`
     
    146152}}}
    147153
    148 === Bigger RST Example
    149 
     154=== Bigger RST Example ===
    150155The example below should be self-explanatory:
    151156
    152157||= Wiki Markup ||= Display ||
    153158{{{#!td
    154 {{{#!html
    155 <pre class="wiki">{{{#!rst
     159{{{
     160#!html
     161<pre class="wiki">{{{
     162#!rst
    156163FooBar Header
    157164=============
     
    181188}}}
    182189{{{#!td
    183 {{{#!rst
     190{{{
     191#!rst
    184192FooBar Header
    185193=============