Differences between revisions 1 and 11 (spanning 10 versions)

ReStructuredText (reST)

ReStructuredText is a complete rewrite of StructuredText by David Goodger.

It is distributed as part of DocUtils. [http://docutils.sourceforge.net/ (project page)] [http://sourceforge.net/project/showfiles.php?group_id=38414 (download)]

More information:

[http://docutils.sourceforge.net/spec/rst/introduction.html An Introduction to ReStructuredText] - goals & history
[http://docutils.sourceforge.net/docs/rst/quickstart.html A ReStructuredText Primer] - how to write reST text
[http://docutils.sourceforge.net/spec/rst/reStructuredText.html ReStructuredText Markup Specification] - details on writing reST text
[http://www.ocf.berkeley.edu/~bac/rest_tutorial.html Brett Cannon's PyCon Tutorial]

MoinMoin contains an (incomplete) bridge to the docutils's parser, you can try this by using "#format rst" as the first line of a wiki page. See RestSample for an example. This of course only works when you use the current CVS version, and when docutils is installed.

Reading reST, Writing HTML

There's surprisingly little on the web and in the documentation about reading reST, and writing HTML.

There's documentation on how to read reST, and output an entire HTML document. But if you want just a fragment of HTML, there's almost nothing.

Here are two approaches that have been found.

The "Official" Way

There is no "official" way, but here's a method that works with the reST system.

   1 from docutils import core
   2 from docutils.writers.html4css1 import Writer,HTMLTranslator
   3 
   4 class HTMLFragmentTranslator( HTMLTranslator ):
   5     def __init__( self, document ):
   6         HTMLTranslator.__init__( self, document )
   7         self.head_prefix = ['','','','','']
   8         self.body_prefix = []
   9         self.body_suffix = []
  10         self.stylesheet = []
  11     def astext(self):
  12         return ''.join(self.body)
  13 
  14 html_fragment_writer = Writer()
  15 html_fragment_writer.translator_class = HTMLFragmentTranslator
  16 
  17 def reST_to_html( s ):
  18     return core.publish_string( s, writer = html_fragment_writer )
  19 
  20 if __name__ == '__main__':
  21     test = """
  22 H1 text
  23 =======
  24 
  25 *Italic* and **Bold.**
  26 
  27 ::
  28 
  29   # Preformatted,
  30   # For communicating code.
  31 
  32   # Yes, it can have spaces.
  33 
  34 Here's a `link to Python.org.`
  35 
  36 __ http://www.python.org/
  37 
  38 List items:
  39 
  40 - item 1
  41 - item 2
  42 - item 3
  43 """
  44     print reST_to_html(test)

If you want everything wrapped in a div tag, (perhaps to, say, delineate a "comment" tag,) you can add the following to the HTMLFragmentTranslator class:

   1     def visit_document(self,node):
   2         self.body.append(self.starttag(node,"div",CLASS="comment"))

These techniques were culled from [http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/193890 an ASPN article,] and connected comments.

The "Easy" Way

IanBicking has contributed this code, which reads a source text (in reST), and writes HTML:

   1 html = docutils.core.publish_string(
   2            source=text,
   3            writer_name='html')
   4 html = html[html.find('<body>')+6:html.find('</body>')].strip()

"It may feel wrong, but it works, and works reliably."

Discussion

(none)

-  ⇤ ← Revision 1 as of 2002-07-16 02:02:16 → 
  Size: 400
  Editor: ipd54b5a02
  Comment:
+   ← Revision 11 as of 2004-02-19 00:02:48 → ⇥
  Size: 3311
  Editor: dsl254-010-130
  Comment: + the "Official" way
-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
-ReStructuredText is a complete rewrite of StructuredText by David Goodger.
+#pragma section-numbers off

= ReStructuredText (reST) =

ReStructuredText is a complete rewrite of StructuredText by David Goodger.

It is distributed as part of DocUtils. [http://docutils.sourceforge.net/ (project page)] [http://sourceforge.net/project/showfiles.php?group_id=38414 (download)]
-Line 5:
+Line 11:
-  * [http://docutils.sourceforge.net/spec/rst/introduction.html An Introduction to ReStructuredText]
  * [http://docutils.sourceforge.net/docs/rst/quickstart.html A ReStructuredText Primer]
  * [http://docutils.sourceforge.net/spec/rst/reStructuredText.html ReStructuredText Markup Specification]
+  * [http://docutils.sourceforge.net/spec/rst/introduction.html An Introduction to ReStructuredText] - goals & history
  * [http://docutils.sourceforge.net/docs/rst/quickstart.html A ReStructuredText Primer] - how to write reST text
  * [http://docutils.sourceforge.net/spec/rst/reStructuredText.html ReStructuredText Markup Specification] - details on writing reST text
  * [http://www.ocf.berkeley.edu/~bac/rest_tutorial.html Brett Cannon's PyCon Tutorial]

{i} MoinMoin contains an (incomplete) bridge to the docutils's parser, you can try this by using "#format rst" as the first line of a wiki page. See MoinMoin:RestSample for an example. This of course only works when you use the current CVS version, and when docutils is installed.

== Reading reST, Writing HTML ==

There's surprisingly little on the web and in the documentation about reading reST, and writing HTML.

There's documentation on how to read reST, and output an entire HTML document. But if you want just a fragment of HTML, there's almost nothing.

Here are two approaches that have been found.

=== The "Official" Way ===

There is no "official" way, but here's a method that works with the reST system.

{{{
#!python
from docutils import core
from docutils.writers.html4css1 import Writer,HTMLTranslator

class HTMLFragmentTranslator( HTMLTranslator ):
    def __init__( self, document ):
        HTMLTranslator.__init__( self, document )
        self.head_prefix = ['','','','','']
        self.body_prefix = []
        self.body_suffix = []
        self.stylesheet = []
    def astext(self):
        return ''.join(self.body)

html_fragment_writer = Writer()
html_fragment_writer.translator_class = HTMLFragmentTranslator

def reST_to_html( s ):
    return core.publish_string( s, writer = html_fragment_writer )

if __name__ == '__main__':
    test = """
H1 text
=======

*Italic* and **Bold.**

::

  # Preformatted,
  # For communicating code.

  # Yes, it can have spaces.

Here's a `link to Python.org.`

__ http://www.python.org/

List items:

- item 1
- item 2
- item 3
"""
    print reST_to_html(test)
}}}

If you want everything wrapped in a div tag, (perhaps to, say, delineate a "comment" tag,) you can add the following to the {{{HTMLFragmentTranslator}}} class:

{{{
#!python
    def visit_document(self,node):
        self.body.append(self.starttag(node,"div",CLASS="comment"))
}}}

These techniques were culled from [http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/193890 an ASPN article,] and connected comments.

=== The "Easy" Way ===

IanBicking has contributed this code, which reads a source text (in reST), and writes HTML:

{{{
#!python
html = docutils.core.publish_string(
           source=text,
           writer_name='html')
html = html[html.find('<body>')+6:html.find('</body>')].strip()
}}}

"It may feel wrong, but it works, and works reliably."

== Discussion ==

  (none)

Page

User

ReStructuredText (reST)

Reading reST, Writing HTML

The "Official" Way

The "Easy" Way

Discussion