Edgewall Software

Changes between Initial Version and Version 1 of WikiRestructuredText


Ignore:
Timestamp:
Jun 3, 2006 8:37:54 AM (9 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
     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=== WikiMacros in reStructuredText ===
     87
     88For doing WikiMacros in ReST you use the same directive as for syntax highlightning i.e
     89code-block. To work you must use a version of trac that has #801 applied.
     90
     91=== WikiMacro Example ===
     92
     93{{{
     94{{{
     95#!rst
     96
     97.. code-block:: HelloWorld
     98 
     99   Something I wanted to say
     100
     101
     102}}}
     103}}}
     104
     105Will result in the below.
     106
     107[[HelloWorld(Something I wanted to say)]]
     108
     109
     110=== Bigger ReST Example ===
     111The example below should be mostly self-explanatory:
     112{{{
     113#!html
     114<pre class="wiki">{{{
     115#!rst
     116FooBar Header
     117=============
     118reStructuredText is **nice**. It has its own webpage_.
     119
     120A table:
     121
     122=====  =====  ======
     123   Inputs     Output
     124------------  ------
     125  A      B    A or B
     126=====  =====  ======
     127False  False  False
     128True   False  True
     129False  True   True
     130True   True   True
     131=====  =====  ======
     132
     133RST TracLinks
     134-------------
     135
     136See also ticket `#42`:trac:.
     137
     138.. _webpage: http://docutils.sourceforge.net/rst.html
     139}}}</pre>
     140}}}
     141
     142
     143Results in:
     144{{{
     145#!rst
     146FooBar Header
     147=============
     148reStructuredText is **nice**. It has its own webpage_.
     149
     150A table:
     151
     152=====  =====  ======
     153   Inputs     Output
     154------------  ------
     155  A      B    A or B
     156=====  =====  ======
     157False  False  False
     158True   False  True
     159False  True   True
     160True   True   True
     161=====  =====  ======
     162
     163RST TracLinks
     164-------------
     165
     166See also ticket `#42`:trac:.
     167
     168.. _webpage: http://docutils.sourceforge.net/rst.html
     169}}}
     170
     171
     172----
     173See also: WikiRestructuredTextLinks, WikiProcessors, WikiFormatting