Home

Documentation

Project Support

Changes in Version 1 of WikiRestructuredText

Author:
trac
Timestamp:
Wed Aug 23 17:34:43 2006

Legend:

Unmodified
Added
Removed
Modified

  • WikiRestructuredText

    v0 v1
      1  = reStructuredText Support in Trac = 
      2   
      3  Trac supports using ''reStructuredText'' (RST) as an alternative to wiki markup in any context WikiFormatting is used. 
      4   
      5  From 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 === 
      9  Note that to activate RST support in Trac, the python docutils package must be installed.  
      10  If 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 == 
      20  To 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   
      53  There is a directive for doing TracSyntaxColoring in ReST as well. The directive is called 
      54  code-block 
      55   
      56  Example 
      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   
      72  Will 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   
      87  === Example === 
      88  The example below should be mostly self-explanatory: 
      89  {{{ 
      90  #!html 
      91  <pre class="wiki">{{{ 
      92  #!rst 
      93  FooBar Header 
      94  ============= 
      95  reStructuredText is **nice**. It has its own webpage_. 
      96   
      97  A table: 
      98   
      99  =====  =====  ====== 
      100     Inputs     Output 
      101  ------------  ------ 
      102    A      B    A or B 
      103  =====  =====  ====== 
      104  False  False  False 
      105  True   False  True 
      106  False  True   True 
      107  True   True   True 
      108  =====  =====  ====== 
      109   
      110  RST TracLinks 
      111  ------------- 
      112   
      113  See also ticket |#42|. 
      114   
      115  .. |#42| trac:: #42 
      116   
      117  .. _webpage: http://docutils.sourceforge.net/rst.html 
      118  }}}</pre> 
      119  }}} 
      120   
      121   
      122  Results in: 
      123  {{{ 
      124  #!rst 
      125  FooBar Header 
      126  ============= 
      127  reStructuredText is **nice**. It has its own webpage_. 
      128   
      129  A table: 
      130   
      131  =====  =====  ====== 
      132     Inputs     Output 
      133  ------------  ------ 
      134    A      B    A or B 
      135  =====  =====  ====== 
      136  False  False  False 
      137  True   False  True 
      138  False  True   True 
      139  True   True   True 
      140  =====  =====  ====== 
      141   
      142  RST TracLinks 
      143  ------------- 
      144   
      145  See also ticket |#42|. 
      146   
      147  .. |#42| trac:: #42 
      148   
      149  .. _webpage: http://docutils.sourceforge.net/rst.html 
      150  }}} 
      151   
      152   
      153  ---- 
      154  See also: WikiRestructuredTextLinks, WikiProcessors, WikiFormatting