Changes between Initial Version and Version 1 of WikiRestructuredText

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