Re: [Docutils-users] Using reST in a Wiki

[David G. <go...@us...>]

These questions are more suitable for the docutils-develop list;
cross-posting.

Ian Bicking wrote:
> To serve as an instructional sample I'm making a very simply Wiki --
> I'd like to use reST as the markup, since it's not an example in
> parsing (and I like the reST markup more than most Wiki markups to
> boot).

Great!  Please share the results if you can.  I know that some
intregration with MoinMoin has been done, although incomplete I
believe.  See
http://twistedmatrix.com/users/jh.twistd/moin/moin.cgi/RestSample

> So, to do this I need to convert reST to HTML.  I looked around in
> buildhtml.py to get an idea, but I found it surprisingly difficult
> to figure out just what I would need to do.

buildhtml.py is a complicated beast, trying to be a kind of "make",
recursively building HTML for regular and PEP files with integrated
local config file support.  It's not a good example to begin with.

> Could someone perhaps tell me what the easiest way to do this is?

First, make sure you're using the latest code from CVS or from the
snapshot: <http://docutils.sf.net/docutils-snapshot.tgz>.  Look in the
docutils/core.py file at the "publish_string" convenience function.
It is probably what you want.

Beyond the docstrings, there is no related developer documentation
yet.  Contributions are, of course, most welcome!

Perhaps the tools/pep2html.py module is a better example, function
"fix_rst_pep".  Docutils is called in one (logical) line of code::

    output = core.publish_string(
        source=''.join(input_lines),
        source_path=inpath,
        destination_path=outfile.name,
        reader_name='pep',
        parser_name='restructuredtext',
        writer_name='pep_html',
        settings=docutils_settings)

> I'm not sure of the relevance of the options, the importance of
> FileIO, or some of the other abstractions involved in this
> operation.

I've since renamed "options" to "settings": they're runtime
configuration settings (see
http://docutils.sf.net/docs/tools.html#configuration-file-entries).
For now, just use a convenience function with no explicit settings;
the defaults should be fine.
 
FileIO is an implementation detail; use strings with "publish_string"
or file-like objects with "publish_file".  Be sure to read the
docstrings.

> Also -- is there a good hook in reST that I can use for Wiki links?
> The linking mechanism reST has is fine for internal and external
> links, but doesn't fit right for Wiki links (which fall somewhere in
> between).  If I could capture failed internal links and turn them
> into inter-wiki-page links, that would be perfect.  Failing that, if
> there was some way I could introduce another markup easily that
> would be great.

There's mention of Wikis as an example potential Reader component in
PEP 258 (http://docutils.sf.net/spec/pep-0258.html#readers).  A Wiki
Reader could subclass the standard parser, or we could build in hooks
if they prove general enough.  The PEP Reader
(docutils/readers/pep.py) first subclassed the parser (still does,
minimally: the "Inliner" class), but most of the code was moved into
the parser proper for other client code to use.

I would suggest that Wiki links retain the trailing "_" of regular
reStructuredText links, and a mechanism be added to do some kind of
lookup from a Wiki target database.  The extra syntax (trailing "_")
removes ambiguity inherent in CamelCase WikiLinks (such as anything
written by Angus MacDuff).

> If there isn't an easy way, I'll probably just look for WikiNames in
> the generated HTML, and do the substitution then.  I'll have to do
> some dynamic fixup anyway, to distinguish between existent Wiki
> pages and to-be-created links.

A proper integrated approach would be best IMO, and welcome.  Please
subscribe to docutils-develop
(http://lists.sf.net/lists/listinfo/docutils-develop) and discuss it
there.  I'll be happy to help.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/