[Doc-SIG] simple use of docutils

[David Goodger]

Michael Hudson wrote:
>>> WHY can't I just pass a filename or a file-like object in as
>>> destination?
>> 
>> I'm trying to provide a uniform interface, no matter the input
>> source (string, single file, multiple files in directories, Python
>> module, Python package) and output destination (string, single
>> file, multiple files), not all of which are implemented yet.  The
>> I/O classes store attributes of their data stores, such as paths
>> and encodings; the I/O classes handle the text decoding & encoding.
> 
> I object (faintly :) to your invention of new classes for this.  Why
> not use what's already there, i.e. the file interface?
> 
> If you want strings, use a StringIO.  The codecs.Stream{Reader,Writer}
> classes handle encodings.  Etc.
...
> It would be nice if you didn't *have* to learn a new set of classes
> to use docutils.  The mantra "easy things should be easy, difficult
> things should be possible" is one I'm quite attached to.

I can see your point, and I agree with what you say in the abstract.
The I/O classes may be a case of adding functionality before it's
required.  However, I'm currently thinking about adding *more*
functionality to these classes.  When you combine all the features
Docutils needs from its I/O, I'm not convinced that doing it piecemeal
is better:

* Multiple input sources: single files, directory trees, Python
  packages, strings.

* Multiple output destinations: single files, directory trees,
  strings.

* 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.

* Encoding support.

The I/O classes are really just implementation details.  Perhaps they
wouldn't be objectionable if better convenience functions existed?
``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.

Of course, I'm open to convincing arguments.  Or better yet,
convincing code. :-)

-- 
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/