Changes between Initial Version and Version 1 of WikiRestructuredText


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