Changes between Version 4 and Version 5 of WikiRestructuredText


Ignore:
Timestamp:
Feb 25, 2025, 12:53:26 PM (5 weeks ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiRestructuredText

    v4 v5  
    1 
    2 = reStructuredText Support in Trac =
    3 
    4 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.
    57
    68From the reStucturedText webpage:
    7  "''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. ''"
    8 
    9 === Requirements ===
    10 Note that to activate RST support in Trac, the python docutils package must be installed.
    11 If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website].
    12 
    13 === More information on RST ===
    14 
    15  * reStructuredText Website -- http://docutils.sourceforge.net/rst.html
    16  * RST Quick Reference -- http://docutils.sourceforge.net/docs/rst/quickref.html
    17 
    18 ----
    19 
    20 == 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
    2126To specify that a block of text should be parsed using RST, use the ''rst'' processor.
    2227
    23 === TracLinks in reStructuredText ===
    24 
    25  * Trac provides a custom RST reference-directive 'trac' to allow TracLinks from within RST text.
    26 
    27  Example:
    28  {{{
    29  {{{
    30  #!rst
    31  This is a reference to |a ticket|
    32 
    33  .. |a ticket| trac:: #42
    34  }}}
    35  }}}
    36 
    37  For a complete example of all uses of the ''trac''-directive, please see WikiRestructuredTextLinks.
    38 
    39 
    40  * Trac allows an even easier way of creating TracLinks in RST, using the custom '':trac:'' link naming scheme.
    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  }}}
    51 
    52 === Syntax highlighting in reStructuredText ===
    53 
    54 There is a directive for doing TracSyntaxColoring in ReST as well. The directive is called
    55 code-block
    56 
    57 Example
    58 
    59 {{{
    60 {{{
    61 #!rst
    62 
    63 .. code-block:: python
    64 
    65  class Test:
    66 
    67     def TestFunction(self):
    68         pass
    69 
    70 }}}
    71 }}}
    72 
    73 Will result in the below.
    74 
    75 {{{
    76 #!rst
    77 
    78 .. code-block:: python
    79 
    80  class Test:
    81 
    82     def TestFunction(self):
    83         pass
    84 
    85 }}}
    86 
    87 
    88 === Example ===
    89 The example below should be mostly self-explanatory:
    90 {{{
    91 #!html
    92 <pre class="wiki">{{{
    93 #!rst
     28=== TracLinks in reStructuredText
     29
     30 * Trac provides a custom RST directive `trac::` to allow TracLinks from within RST text.
     31   ||= Wiki Markup ||= Display ||
     32   {{{#!td
     33     {{{
     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
     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     {{{#!rst
     62     This is a reference to ticket `#12`:trac:
     63
     64     To learn how to use Trac, see `TracGuide`:trac:
     65     }}}
     66   }}}
     67
     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
     78
     79  .. code-block:: python
     80
     81     class Test:
     82
     83         def TestFunction(self):
     84             pass
     85 
     86  }}}
     87  }}}
     88}}}
     89{{{#!td
     90  {{{#!rst
     91
     92  .. code-block:: python
     93
     94     class Test:
     95
     96         def TestFunction(self):
     97             pass
     98
     99  }}}
     100}}}
     101Note the need to indent the code at least one character after the `.. code-block` directive.
     102
     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:
     130
     131||= Wiki Markup ||= Display ||
     132{{{#!td
     133  {{{
     134  {{{
     135  #!rst
     136
     137  :code-block:`RecentChanges:Trac,3`
     138  }}}
     139  }}}
     140}}}
     141{{{#!td
     142  {{{#!rst
     143
     144  :code-block:`RecentChanges:Trac,3`
     145  }}}
     146}}}
     147
     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
    94156FooBar Header
    95157=============
    … …  
    112174-------------
    113175
    114 See also ticket |#42|.
    115 
    116 .. |#42| trac:: #42
     176See also ticket `#42`:trac:.
    117177
    118178.. _webpage: http://docutils.sourceforge.net/rst.html
    119179}}}</pre>
    120180}}}
    121 
    122 
    123 Results in:
    124 {{{
    125 #!rst
     181}}}
     182{{{#!td
     183{{{#!rst
    126184FooBar Header
    127185=============
    … …  
    144202-------------
    145203
    146 See also ticket |#42|.
    147 
    148 .. |#42| trac:: #42
     204See also ticket `#42`:trac:.
    149205
    150206.. _webpage: http://docutils.sourceforge.net/rst.html
    151207}}}
    152 
     208}}}
    153209
    154210----