Subject: Re: [Docutils-develop] Merging Pudge into Docutils
Date: February 13, 2006 10:14:10 PM PST (CA)
Apropos to nothing, it would be extremely interesting to extend Pudge
to include actual source code embedded it, including the use of LEO
Literate Editor-style references/hyperlinks, to "hide" code at the
For example, the page on http://pudge.lesscode.org/module-
pudge.rst.html could *easily* be written to include the top-level LEO-
abbreviated code that forms the heart of the pudge_rst.py module:
--SNIP! This is cut-and-paste from the source code itself! http://
0011 def parts(file):
0013 Parse ``file`` and return a dictionary containing transformed
0015 This uses the ``docutils.core.publish_parts`` function
0016 Interesting parts include the following:
0019 The body without the header, title, or footer.
0022 The document title.
--SNIP! This is what the web page currently says! --
f parts(file) ...
Parse file and return a dictionary containing transformed parts.
This uses the docutils.core.publish_parts function internally.
Interesting parts include the following:
The body without the header, title, or footer.
The document title.
--SNAP! This is the actual source code for f.parts(file) itself,
0025 fo = open(file, 'r')
0026 source = fo.read()
0028 parts = publish_parts(source, source_path=file,
0029 for k, v in parts.items():
0030 parts[k] = _scrub_html(v)
0031 return parts
(line numbers courtesy of the source code rendering on that webpage)
--SNAP! The source code *could be written* as a LEO application--
<< load the ReST-markup'd source file >>
# pass content to Docutils as source for HTML
parts = publish_parts(source, source_path=file, writer_name='html')
<< scrub parts >>
But it would be rendered specially by the webpage, with proper click-
the sourcecode as it is written in an input form to generate live-
action HTML renderings of same.
Put it into a Wiki environment. You have a wiki environment for
source code documentation *and* source code itself. That's Literate
Editing, exerted community-style. The documentation becomes the
source code. The emphasis is on the Literate end: the program has to
do what it says it does, or else someone's gonna notice that it's
wrong. Makes it easier for the community to actually track down the
bug, let alone assist in fixing it.
(Sensibly, one would probably modify the stereotypical wiki such that
there's a means for users to append comments and debate directly
where they think the problem is, not necessarily that they can
actually get in and damage source code with the greatest of ease.
Perhaps they could change the LEO-reference name of a subunit of the
program, but not the in-code commentary; or perhaps the in-code, but
not the sourcecode. Whatever.)
I'm envisioning a cross-breed Wiki, LEO hierarchy with clones and
ability to cross-reference both via description and hyperlinking, and
Pudge code-grammar writing automation.
If this makes sense to anyone, I'd *love* to see it implemented. I
don't know if it would be a relatively easy project of linking the
existing applications, or whether it would require smashing Pudge and
MoinMoin together, or what. Maybe it's taking the best ideas from
all of them. I think it's the obvious connection between these major
projects (MoinMoin, LEO, and Docutils all have sizable communities),
but no one seems to have done it, so maybe I'm out to lunch...
(And with that wiki, imagine working on writing the documentation for
Python itself. I mean, pudge.rst.parts() used in the example above
is in a file that imports sys, so presumably there's a link to that
module, just like there was a link to pudge.rst.parts()...)
On 13-Feb-06, at 8:00 PM, Ian Bicking wrote:
> Pudge (http://pudge.lesscode.org/) has been in a bit of a limbo
> I've found it very useful -- it's not the fanciest or most featureful
> system, but it does all the things I (and several other people)
> need for a documentation generation system to do.
> Pudge overlaps and compliments docutils. But I also think it offers a
> pragmatic way to use docutils to do what docutils was originally meant
> for -- generate useful code documentation.
> But, the main author of Pudge has moved on to other things, and the
> project is in a bit of a limbo. There's some infrastructure issues
> -- repositories and access and whatnot -- but these are
> resolveable. But I'd also be interested if we can just pull all
> these ideas together and create a cohesive system for docutils. I
> think many other systems are either overdesigned (to the point
> where they don't really get completed), or perhaps misfocused. Or
> maybe this is just the nature of documentation extraction systems,
> as Pudge is actually very like so many others that have entered
> this same state of limbo.
> Anyway, I'm interested what people think about this.
> Ian Bicking / ianb@... / http://blog.ianbicking.org
> This SF.net email is sponsored by: Splunk Inc. Do you grep through
> log files
> for problems? Stop! Download the new AJAX search engine that makes
> searching your log files as easy as surfing the web. DOWNLOAD
> Docutils-develop mailing list
> Please use "Reply All" to reply to the list.
David Priest priest@...
ICQ: 248533102 MSN: omgeleventyone@...