bsmai is hosted by Hepforge, IPPP Durham

Changes between Version 1 and Version 2 of WikiRestructuredText


Ignore:
Timestamp:
Jul 17, 2018, 2:09:56 PM (6 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiRestructuredText

    v1 v2  
    1 = reStructuredText Support in Trac =
     1= reStructuredText Support in Trac
     2
     3== Introduction
     4
    25
    36Trac 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 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 ===
    11 To 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 
    13 Do 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 ==
     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
    2326To specify that a block of text should be parsed using RST, use the ''rst'' processor.
    2427
    25 === TracLinks in reStructuredText ===
     28=== TracLinks in reStructuredText
    2629
    2730 * Trac provides a custom RST directive `trac::` to allow TracLinks from within RST text.
    … …  
    2932   {{{#!td
    3033     {{{
     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
    3152     {{{
    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
     53     {{{#!rst
    5454     This is a reference to ticket `#12`:trac:
    5555
    … …  
    5959   }}}
    6060   {{{#!td
    61      {{{
    62      #!rst
     61     {{{#!rst
    6362     This is a reference to ticket `#12`:trac:
    6463
    … …  
    6766   }}}
    6867
    69  For a complete example of all uses of the `:trac:` role, please see WikiRestructuredTextLinks.
    70 
    71 === Syntax highlighting in reStructuredText ===
     68 For a complete example of all uses of the `:trac:` role, see WikiRestructuredTextLinks.
     69
     70=== Syntax highlighting in reStructuredText
    7271
    7372There is a directive for doing TracSyntaxColoring in RST as well. The directive is called code-block:
    … …  
    7675{{{#!td
    7776  {{{
    78   {{{
    79   #!rst
     77  {{{#!rst
    8078
    8179  .. code-block:: python
    … …  
    9088}}}
    9189{{{#!td
    92   {{{
    93   #!rst
     90  {{{#!rst
    9491
    9592  .. code-block:: python
    … …  
    104101Note the need to indent the code at least one character after the `.. code-block` directive.
    105102
    106 === Wiki Macros in reStructuredText ===
    107 
    108 To enable [WikiMacros Wiki Macros] in RST, you use the same directive as for syntax highlighting, ie 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:
    109130
    110131||= Wiki Markup ||= Display ||
    … …  
    114135  #!rst
    115136
    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 
    134 Or 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 
    142137  :code-block:`RecentChanges:Trac,3`
    143138  }}}
    … …  
    145140}}}
    146141{{{#!td
    147   {{{
    148   #!rst
     142  {{{#!rst
    149143
    150144  :code-block:`RecentChanges:Trac,3`
    … …  
    152146}}}
    153147
    154 === Bigger RST Example ===
     148=== Bigger RST Example
     149
    155150The example below should be self-explanatory:
    156151
    157152||= Wiki Markup ||= Display ||
    158153{{{#!td
    159 {{{
    160 #!html
    161 <pre class="wiki">{{{
    162 #!rst
     154{{{#!html
     155<pre class="wiki">{{{#!rst
    163156FooBar Header
    164157=============
    … …  
    188181}}}
    189182{{{#!td
    190 {{{
    191 #!rst
     183{{{#!rst
    192184FooBar Header
    193185=============