[Doc-SIG] simple use of docutils

[David Goodger]

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

Not to worry, no offense taken. :-)

> I realise this is a work in progress, etc.

Indeed!  I'm currently puzzling out a re-design of the transform
mechanism, since the original/current design proved that it wasn't up
to snuff.  Also, there are many small things that crop up.  For
example, I'm considering renaming "options" to "settings".  (Effective
naming is very important to me. It helps me keep the design in my
head.)

Please consider the entire codebase and design to be extremely
experimental, subject to and welcoming of change.  Improvements are
accepted in any form from any source.  I try to distance myself from
the existing code and design, to objectively judge it against
alternatives (not always easy).

If you'd like to join the project, just let me know.  That goes for
anybody who's interested in helping with Docutils.

> I hope I'll be able to supply some patches as well as just grousing.

That would be most welcome (on both counts ;-).

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

I think it's hard for the developer (me) to objectively document their
own code, since they *do* already understand it.  Contributions in
this regard (questions, suggestions, actual docs and/or docstrings)
would also be welcome!

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

The only "big picture" can be found in PEPs 256 & 258, especially the
latter.  They're kept up to date.

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

Having said that, if there's a simpler way then I'm all ears.

> Having to wrap things up in a layer of library specific classes rubs
> me up the wrong way.

Does the above justify it to you now?  If not, I'm open to
suggestions.  Although I think the I/O classes are a decent solution,
I'm not 100% sure they don't smell bad.  Sometimes it's hard to tell
until you've seen a better solution.

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

Agreed.  Returning the value was an afterthought.  How about this
instead? ::

    pub.set_options()
    options = pub.options

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

That code won't work.  As I wrote to Aahz, the "pub.set_reader" and
"pub.set_writer" calls have to come *before* "pub.set_options".  My
mistake, sorry.

> I know I'm going to have to get a bit more cosy with the library at
> some point:

Out of curiosity, what will you be using Docutils for?

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

I don't understand what you mean by "the heading" here.  Can you
explain?

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

Cool.

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