[Doc-SIG] simple use of docutils

[Michael Hudson]

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

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

Good.

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

Maybe.  I'm not really at that point (yet?).

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

OK.

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

PEP 258 seems to be what I needed.

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

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

See above, maybe.

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

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.

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

That would be better, I think.  Seems a bit more regular.

> >> 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've gotten this to work, in the end.  The code's on my laptop though,
so I can't post it just yet.

> > 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 was thinking of writing a blog tool.  I'm not sure another blog tool
is what the world most desparately needs right now, but all the ones I
can find annoy me in non-trivial ways (basically by being too
complicated -- I am *not* going to install MySQL just for a blog!).

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

Well, I'm assuming that each blog entry will start with a heading.
line.  That's all.  It seems docutils already knows about this sort of
thing, as it ends up in the <title> tag...

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

Unfortunately <wink> most of my trains journeys were spent playing ev
nova...

Cheers,
M.

-- 
  I have a cat, so I know that when she digs her very sharp claws into
  my chest or stomach it's really a sign of affection, but I don't see
  any reason for programming languages to show affection with pain.
                                        -- Erik Naggum, comp.lang.lisp