Changes between Initial Version and Version 1 of WikiRestructuredText


Ignore:
Timestamp:
Oct 2, 2014, 4:55:41 PM (10 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WikiRestructuredText

    v1 v1  
     1= reStructuredText Support in Trac =
     2
     3Trac supports using ''reStructuredText'' (RST) as an alternative to wiki markup in any context WikiFormatting is used.
     4
     5From 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
     8If 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 ===
     11Note that to activate RST support in Trac, the python docutils package must be installed.
     12If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website].
     13
     14Install 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 ==
     24To specify that a block of text should be parsed using RST, use the ''rst'' processor.
     25
     26=== TracLinks in reStructuredText ===
     27
     28 * 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 }}}
     39
     40 * 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 }}}
     51
     52 For a complete example of all uses of the `:trac:` role, please see WikiRestructuredTextLinks.
     53
     54
     55=== Syntax highlighting in reStructuredText ===
     56
     57There is a directive for doing TracSyntaxColoring in RST as well. The directive is called
     58code-block
     59
     60Example
     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
     76Will 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
     92For doing [WikiMacros Wiki Macros] in RST you use the same directive as for syntax highlighting i.e
     93code-block. To work you must use a version of trac that has [trac:ticket:801 #801] applied.
     94
     95=== Wiki Macro Example ===
     96
     97{{{
     98{{{
     99#!rst
     100
     101.. code-block:: RecentChanges
     102
     103   Trac,3
     104
     105}}}
     106}}}
     107
     108Will result in the below:
     109
     110     [[RecentChanges(Trac,3)]]
     111
     112Or a more concise Wiki Macro like syntax is also available:
     113
     114{{{
     115{{{
     116#!rst
     117
     118:code-block:`RecentChanges:Trac,3`
     119}}}
     120}}}
     121
     122=== Bigger RST Example ===
     123The example below should be mostly self-explanatory:
     124{{{
     125#!html
     126<pre class="wiki">{{{
     127#!rst
     128FooBar Header
     129=============
     130reStructuredText is **nice**. It has its own webpage_.
     131
     132A table:
     133
     134=====  =====  ======
     135   Inputs     Output
     136------------  ------
     137  A      B    A or B
     138=====  =====  ======
     139False  False  False
     140True   False  True
     141False  True   True
     142True   True   True
     143=====  =====  ======
     144
     145RST TracLinks
     146-------------
     147
     148See also ticket `#42`:trac:.
     149
     150.. _webpage: http://docutils.sourceforge.net/rst.html
     151}}}</pre>
     152}}}
     153
     154
     155Results in:
     156{{{
     157#!rst
     158FooBar Header
     159=============
     160reStructuredText is **nice**. It has its own webpage_.
     161
     162A table:
     163
     164=====  =====  ======
     165   Inputs     Output
     166------------  ------
     167  A      B    A or B
     168=====  =====  ======
     169False  False  False
     170True   False  True
     171False  True   True
     172True   True   True
     173=====  =====  ======
     174
     175RST TracLinks
     176-------------
     177
     178See also ticket `#42`:trac:.
     179
     180.. _webpage: http://docutils.sourceforge.net/rst.html
     181}}}
     182
     183
     184----
     185See also: WikiRestructuredTextLinks, WikiProcessors, WikiFormatting