Changes between Initial Version and Version 1 of WikiRestructuredText


Ignore:
Timestamp:
07/20/10 20:12:24 (14 years ago)
Author:
trac (IP: 127.0.0.1)
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
     8=== Requirements ===
     9Note that to activate RST support in Trac, the python docutils package must be installed.
     10If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website].
     11
     12=== More information on RST ===
     13
     14 * reStructuredText Website -- http://docutils.sourceforge.net/rst.html
     15 * RST Quick Reference -- http://docutils.sourceforge.net/docs/rst/quickref.html
     16
     17----
     18
     19== Using RST in Trac ==
     20To specify that a block of text should be parsed using RST, use the ''rst'' processor.
     21
     22=== TracLinks in reStructuredText ===
     23
     24 * Trac provides a custom RST reference-directive 'trac' to allow TracLinks from within RST text.
     25
     26 Example:
     27 {{{
     28 {{{
     29 #!rst
     30 This is a reference to |a ticket|
     31
     32 .. |a ticket| trac:: #42
     33 }}}
     34 }}}
     35
     36 For a complete example of all uses of the ''trac''-directive, please see WikiRestructuredTextLinks.
     37
     38
     39 * Trac allows an even easier way of creating TracLinks in RST, using the custom '':trac:'' link naming scheme.
     40
     41 Example:
     42 {{{
     43 {{{
     44 #!rst
     45 This is a reference to ticket `#12`:trac:
     46
     47 To learn how to use Trac, see `TracGuide`:trac:
     48 }}}
     49 }}}
     50
     51=== Syntax highlighting in reStructuredText ===
     52
     53There is a directive for doing TracSyntaxColoring in ReST as well. The directive is called
     54code-block
     55
     56Example
     57
     58{{{
     59{{{
     60#!rst
     61
     62.. code-block:: python
     63
     64 class Test:
     65
     66    def TestFunction(self):
     67        pass
     68
     69}}}
     70}}}
     71
     72Will result in the below.
     73
     74{{{
     75#!rst
     76
     77.. code-block:: python
     78
     79 class Test:
     80
     81    def TestFunction(self):
     82        pass
     83
     84}}}
     85
     86=== Wiki Macros in reStructuredText ===
     87
     88For doing [WikiMacros Wiki Macros] in ReST you use the same directive as for syntax highlighting i.e
     89code-block. To work you must use a version of trac that has #801 applied.
     90
     91=== Wiki Macro Example ===
     92
     93{{{
     94{{{
     95#!rst
     96
     97.. code-block:: RecentChanges
     98
     99   Trac,3
     100
     101}}}
     102}}}
     103
     104Will result in the below:
     105
     106     [[RecentChanges(Trac,3)]]
     107
     108Or a more concise Wiki Macro like syntax is also available:
     109
     110{{{
     111{{{
     112#!rst
     113
     114:code-block:`RecentChanges:Trac,3`
     115}}}
     116}}}
     117
     118=== Bigger ReST Example ===
     119The example below should be mostly self-explanatory:
     120{{{
     121#!html
     122<pre class="wiki">{{{
     123#!rst
     124FooBar Header
     125=============
     126reStructuredText is **nice**. It has its own webpage_.
     127
     128A table:
     129
     130=====  =====  ======
     131   Inputs     Output
     132------------  ------
     133  A      B    A or B
     134=====  =====  ======
     135False  False  False
     136True   False  True
     137False  True   True
     138True   True   True
     139=====  =====  ======
     140
     141RST TracLinks
     142-------------
     143
     144See also ticket `#42`:trac:.
     145
     146.. _webpage: http://docutils.sourceforge.net/rst.html
     147}}}</pre>
     148}}}
     149
     150
     151Results in:
     152{{{
     153#!rst
     154FooBar Header
     155=============
     156reStructuredText is **nice**. It has its own webpage_.
     157
     158A table:
     159
     160=====  =====  ======
     161   Inputs     Output
     162------------  ------
     163  A      B    A or B
     164=====  =====  ======
     165False  False  False
     166True   False  True
     167False  True   True
     168True   True   True
     169=====  =====  ======
     170
     171RST TracLinks
     172-------------
     173
     174See also ticket `#42`:trac:.
     175
     176.. _webpage: http://docutils.sourceforge.net/rst.html
     177}}}
     178
     179
     180----
     181See also: WikiRestructuredTextLinks, WikiProcessors, WikiFormatting