Changes between Initial Version and Version 1 of WikiRestructuredText


Ignore:
Timestamp:
09/16/10 12:25:38 (14 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 
     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 code-block. 
     93 
     94=== Wiki Macro Example === 
     95 
     96{{{ 
     97{{{ 
     98#!rst 
     99 
     100.. code-block:: RecentChanges 
     101 
     102   Trac,3 
     103 
     104}}} 
     105}}} 
     106 
     107Will result in the below: 
     108 
     109     [[RecentChanges(Trac,3)]] 
     110 
     111Or a more concise Wiki Macro like syntax is also available: 
     112 
     113{{{ 
     114{{{ 
     115#!rst 
     116 
     117:code-block:`RecentChanges:Trac,3` 
     118}}} 
     119}}} 
     120 
     121=== Bigger RST Example === 
     122The example below should be mostly self-explanatory: 
     123{{{ 
     124#!html 
     125<pre class="wiki">{{{ 
     126#!rst 
     127FooBar Header 
     128============= 
     129reStructuredText is **nice**. It has its own webpage_. 
     130 
     131A table: 
     132 
     133=====  =====  ====== 
     134   Inputs     Output 
     135------------  ------ 
     136  A      B    A or B 
     137=====  =====  ====== 
     138False  False  False 
     139True   False  True 
     140False  True   True 
     141True   True   True 
     142=====  =====  ====== 
     143 
     144RST TracLinks 
     145------------- 
     146 
     147See also ticket `#42`:trac:. 
     148 
     149.. _webpage: http://docutils.sourceforge.net/rst.html 
     150}}}</pre> 
     151}}} 
     152 
     153 
     154Results in: 
     155{{{ 
     156#!rst 
     157FooBar Header 
     158============= 
     159reStructuredText is **nice**. It has its own webpage_. 
     160 
     161A table: 
     162 
     163=====  =====  ====== 
     164   Inputs     Output 
     165------------  ------ 
     166  A      B    A or B 
     167=====  =====  ====== 
     168False  False  False 
     169True   False  True 
     170False  True   True 
     171True   True   True 
     172=====  =====  ====== 
     173 
     174RST TracLinks 
     175------------- 
     176 
     177See also ticket `#42`:trac:. 
     178 
     179.. _webpage: http://docutils.sourceforge.net/rst.html 
     180}}} 
     181 
     182 
     183---- 
     184See also: WikiRestructuredTextLinks, WikiProcessors, WikiFormatting