Docutils: Documentation Utilities

On 7/7/06, Felix Wiemann <Felix.Wiemann@...> wrote:
> We're considering to re-use parts (maybe large parts) of the Docutils
> infrastructure for the MoinMoin project.

What are you trying to accomplish and why?
I can't comment on your ideas (except for a knee-jerk "no way!" ;-)
without more background.

> Any suggestions how to extend the doctree *right now*, without changing
> Docutils?  Just copy all module contents of nodes.py to a MoinMoin nodes
> module and extend it?  That's not quite clean, but it should work for now.

"Subclass" the module itself, by duplicating its namespace:

"""
from docutils.nodes import *

class strikeout(Inline, TextElement):
...
"""

-- 
David Goodger <http://python.net/~goodger>

David Goodger wrote:

> Felix Wiemann <Felix.Wiemann@...> wrote:
 >
>> We're considering to re-use parts (maybe large parts) of the Docutils
>> infrastructure for the MoinMoin project.
> 
> What are you trying to accomplish and why?

Well, the MoinMoin wiki uses a parser/formatter system which works 
basically like this:

The input text is parsed by the parser, which immediately calls the 
formatter (e.g. formatter.emphasis(1) when the emphasis starts, and 
formatter.emphasis(0) when the emphasis ends).

You have e.g. a moin_wiki parser and an html formatter, but there are 
many more.  If you want to look at the HTML formatter, see this:
http://hg.thinkmo.de/moin/1.6?f=05b1be96814e;file=MoinMoin/formatter/text_html.py
(To get the whole MoinMoin repository, go here: 
http://moinmoin.wikiwikiweb.de/MoinDev/MercurialGuide)

Now, this approach suffers from inflexibility because no intermediate 
doctree is generated (on which e.g. transforms could be applied).  Now, 
instead of re-inventing the wheel, MoinMoin could use Docutils' document 
tree.  This would also allow us to re-use many of Docutils' modules with 
little modifications for MoinMoin (e.g. the excellent HTML writer).  And 
Docutils might grow a few parsers (at least as plugins), most notably a 
moin_wiki parser.

MoinMoin would need to extend Docutils' document tree a little, however. 
  E.g. it needs underline and strike-through.  But overall it seems that 
most current MoinMoin elements are rather cleanly mappable to Docutils' 
document tree.

The whole point of this is sharing code, so that the two projects can 
benefit from each other.

> "Subclass" the module itself, by duplicating its namespace:
> 
> """
> from docutils.nodes import *
> 
> class strikeout(Inline, TextElement):
> ...
> """

Cool.  Thanks.

Felix

-- 
Felix Wiemann -- http://www.ososo.de/