Changes between Initial Version and Version 1 of WikiRestructuredText


Ignore:
Timestamp:
Nov 27, 2008 1:30:31 AM (16 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 reference-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 For a complete example of all uses of the ''trac''-directive, please see WikiRestructuredTextLinks.
     39
     40
     41 * Trac allows an even easier way of creating TracLinks in RST, using the custom '':trac:'' link naming scheme.
     42
     43 Example:
     44 {{{
     45 {{{
     46 #!rst
     47 This is a reference to ticket `#12`:trac:
     48
     49 To learn how to use Trac, see `TracGuide`:trac:
     50 }}}
     51 }}}
     52
     53=== Syntax highlighting in reStructuredText ===
     54
     55There is a directive for doing TracSyntaxColoring in ReST 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 ReST 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 ReST 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