[Doc-SIG] simple use of docutils

[Michael Hudson]

David Goodger <goodger@users.sourceforge.net> writes:

> Michael Hudson wrote:
> > I have an application where I want to programmatically use docutils.
> > 
> > So, I have a chuck of text (or a file, both are equally easy) in rst
> > format that I want to turn into html (again, either a file, or as
> > text).
> > 
> > This doesn't seem to be totally straightforward.
> 
> Questions and constructive suggestions are always appreciated.

First off, let me apologise for being a bit peeved when writing last
night's mail.  It wasn't all docutils fault :)

I realise this is a work in progress, etc.  I hope I'll be able to
supply some patches as well as just grousing.

> > Clearly, I haven't really read the docs.
> 
> That's understandable, since there are none yet for what you're doing.
> But you must have read the source to get this far.  Look at the
> docstrings of the classes you're using and their __init__ methods for
> details.  I've employed "attribute docstrings" liberally, in
> anticipation of future tool support.

I'm afraid the docstrings slightly suffer from the problem of only
making sense if you already understand what's going on.

I guess I'm missing the "big picture", and docstrings aren't really
the place to get that.

> > I have code like this:
> > 
> >     from docutils.core import Publisher
> >     from docutils.io import FileInput
> > 
> >     pub = Publisher(source=FileInput(None, source_path=filename),
> >                     destination=htname)
> 
> What is "htname"?  The "destination" parameter has to be a
> docutils.io.Output instance, such as FileOutput or StringOutput.

Yeah, I realised that I'd need to fiddle that sooner or later, but I
hadn't got that far...

But, here's a real point: WHY?

WHY can't I just pass a filename or a file-like object in as
destination?  Having to wrap things up in a layer of library specific
classes rubs me up the wrong way.

> >     pub.set_options()
> >     pub.set_reader('standalone', None, 'restructuredtext')
> >     pub.set_writer('html')
> >     pub.publish()
> > 
> > But that's not enough -- I have to cook up mythical 'option' objects
> > from somewhere.
> 
> Just replace "pub.set_options()" with::
> 
>     options = pub.set_options()

Ah!  OK.

> "Publisher.set_options()" sets *and* returns the option values object.

This is not an intuitive interface, to my mind.

> You'll need to pass the options object to the I/O instantiators.  This
> code should work (assuming you want a string return value)::
> 
>     from docutils.core import Publisher
>     from docutils.io import FileInput, StringOutput
> 
>     pub = Publisher()
>     options = pub.set_options()
>     pub.source = FileInput(options, source_path=filename)
>     pub.destination = StringOutput(options)
>     pub.set_reader('standalone', None, 'restructuredtext')
>     pub.set_writer('html')
>     output = pub.publish()

Thanks, I'll give it a try momentarily.

> > Is there an easy way of doing what I want?
> 
> The "docutils.core.publish()" convenience function is an easy way to
> get file-to-file processing.  The to-do list has an entry for a
> string-to-string processing convenience function, which I can whip up
> quickly if it will help.  But I can't make one for every possible
> combination; that's up to the developer.

Of course.

I know I'm going to have to get a bit more cosy with the library at
some point: I don't really want to go .rst file -> .html file, I want
to go chunk of restructured text -> chunk of html, and I'll want to
know what the heading of the chunk of restructured text actually was.

> > There should be.

[aside: this should be read as "there should be, at some point", not
"there should be, already"]

> The standard disclaimer applies: if something isn't there, it's either
> because nobody has needed it yet or because nobody has had time to add
> it yet.  Patches are welcome!

I have a couple of train journeys this weekend; I'll see what I can
come up with.

Cheers,
M.

-- 
  I'm a keen cyclist and I stop at red lights.  Those who don't need
  hitting with a great big slapping machine.
                                           -- Colin Davidson, cam.misc