Wiki

Changes between Initial Version and Version 1 of WikiRestructuredText

Show
Ignore:
Timestamp:
02/23/08 22:54:25 (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 
     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 [TracWikiMacros 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:: 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 
     109Or a more concise WikiMacro like syntax is also available: 
     110 
     111{{{ 
     112{{{ 
     113#!rst 
     114 
     115:code-block:`HelloWorld:Something I wanted to say` 
     116}}} 
     117}}} 
     118 
     119=== Bigger ReST Example === 
     120The example below should be mostly self-explanatory: 
     121{{{ 
     122#!html 
     123<pre class="wiki">{{{ 
     124#!rst 
     125FooBar Header 
     126============= 
     127reStructuredText is **nice**. It has its own webpage_. 
     128 
     129A table: 
     130 
     131=====  =====  ====== 
     132   Inputs     Output 
     133------------  ------ 
     134  A      B    A or B 
     135=====  =====  ====== 
     136False  False  False 
     137True   False  True 
     138False  True   True 
     139True   True   True 
     140=====  =====  ====== 
     141 
     142RST TracLinks 
     143------------- 
     144 
     145See also ticket `#42`:trac:. 
     146 
     147.. _webpage: http://docutils.sourceforge.net/rst.html 
     148}}}</pre> 
     149}}} 
     150 
     151 
     152Results in: 
     153{{{ 
     154#!rst 
     155FooBar Header 
     156============= 
     157reStructuredText is **nice**. It has its own webpage_. 
     158 
     159A table: 
     160 
     161=====  =====  ====== 
     162   Inputs     Output 
     163------------  ------ 
     164  A      B    A or B 
     165=====  =====  ====== 
     166False  False  False 
     167True   False  True 
     168False  True   True 
     169True   True   True 
     170=====  =====  ====== 
     171 
     172RST TracLinks 
     173------------- 
     174 
     175See also ticket `#42`:trac:. 
     176 
     177.. _webpage: http://docutils.sourceforge.net/rst.html 
     178}}} 
     179 
     180 
     181---- 
     182See also: WikiRestructuredTextLinks, WikiProcessors, WikiFormatting