Changes between Initial Version and Version 1 of WikiRestructuredText


Ignore:
Timestamp:
01/06/08 13:29:56 (17 years ago)
Author:
trac (IP: 127.0.0.1)
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