## page was renamed from ReStructuredText #pragma section-numbers off = reStructuredText (reST) = reStructuredText is a complete rewrite of StructuredText by David Goodger. It is distributed as part of Docutils. * Project page: [[http://docutils.sourceforge.net/]] * Release download: [[http://sourceforge.net/project/showfiles.php?group_id=38414]] * Development snapshots: [[http://docutils.sourceforge.net/#development-snapshots]] 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]] {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('')+6:html.find('')].strip() }}} "It may feel wrong, but it works, and works reliably." === The "Cool" Way === "This sure is a lot cooler and generates a nice and more kosher html fragment from the 'official' reST-to-html fragment example above."-MaxPa {{{ #!python from docutils import core def reST_to_html_fragment(a_str): parts = core.publish_parts( source=a_str, writer_name='html') return parts['body_pre_docinfo']+parts['fragment'] }}} === See Also: === PyTextile is a similar, but different, text-to-html converter. It was originally intended for HTML fragments, unlike reStructuredText. == Discussion == I've been having problems getting reST to work from a blog script I've written. It seems that there's a part in Publisher where I'm triggering an exception, and then Publisher calls ''exit,'' so I can't see what's wrong. I'll leave notes here if I figure out how to get around this problem. -- LionKimbro No luck finding a way to get around the publisher's exit, but I did find something interesting: http://sourceforge.net/mailarchive/forum.php?thread_id=3740457&forum_id=8812 -- LionKimbro