Changes between Initial Version and Version 1 of WikiRestructuredText

Show
Ignore:
Timestamp:
03/03/11 20:59:24 (3 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=== 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