[Doc-SIG] simple use of docutils

[David Goodger]

Michael Hudson wrote:
>> * Multiple input sources: single files, directory trees, Python
>>   packages, strings.
> 
> What's the interface going to be for these?  Here's a suggestion: a
> file-like object or something you can iterate over to get file-like
> objects.  That covers all the above rather easily.

I'm not sure what the interface will be; haven't got there yet.
Suggestion noted.

>> * Multiple output destinations: single files, directory trees,
>>   strings.
> 
> single files & strings are easily handled by file-like objects.
> What interface do you suggest for outputting to multiple files?

Don't know yet. :-)

>> * Transforms (& maybe command-line options) associated with the
>>   source/destination type.  For example, a "split a monolithic
>>   document tree into multiple doctrees" transform for the directory
>>   tree output destination.  This is something we're currently
>>   discussing on the docutils-develop list.
> 
> Well, I don't know what this means, so I can't really comment.

Overview at http://docutils.sf.net/spec/pep-0258.html#transforms

> Sigh, another mailing list to join...

:-)  Sign up for the docutils-develop@lists.sf.net mailing list at
http://lists.sourceforge.net/lists/listinfo/docutils-users .

>> * Encoding support.
> 
> This is what codes.Stream{Reader,Writer} are for.

I've had enough trouble grokking Unicode encodings.  The docs for the
codecs module are rather opaque and beyond my patience at the moment.
Do you know of a gentle introduction?

Having gone through the pain of figuring it all out, I'd rather
relieve the client code (and thus, Docutils developers) from the
responsibility of handling Unicode decoding & encoding (unless it/they
want to, of course!).  So it's handled by the I/O classes.  If it's
better to do the handling with codecs.StreamReader/.StreamWriter,
that's an implementation detail.  I'm comfortable with the current
set-up; if you're not: patches welcome!

>> The I/O classes are really just implementation details.  Perhaps they
>> wouldn't be objectionable if better convenience functions existed?
> 
> Perhaps.
> 
>> ``docutils.core.publish()`` provides a dirt-simple interface for
>> file-to-file command-line processing (including stdin-to-stdout).
>> Would a ``publish_string`` convenience funcion (providing
>> string-to-string programmatic processing) appease you?  Given that,
>> you could do your own I/O.
> 
> True.

I've added convenience functions to docutils.core, complete with
documentation: "publish_file()" for file-like object I/O (example in
tools/buildhtml.py) and "publish_string()" for string I/O (example in
tools/pep2html.py).  Please take a look.  I've also renamed the old
"publish()" function to "publish_cmdline()" to emphasize its
relationship to command-line front-end tools.

-- 
David Goodger  <goodger@users.sourceforge.net>  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/