Re: [Docutils-develop] Putting docutils into Zope 2.5.1

[David G. <go...@us...>]

Richard Jones wrote:
> One of the big issues is that I'm not sure what all the options are :)

Have you read http://docutils.sf.net/docs/tools.html yet?  It's up to date.

> Stylesheet location and Reporter verbosity are two biggies at the moment.

``options.stylesheet``, ``options.report_level``, and
``options.halt_level``.

> I'd want to capture the Reporter output to display on the Zope edit page,
> rather than it just going to stdout/err ;)

It would be easy to capture the stderr stream::

    sys.stderr = my_stream_object

Reading ahead though, I guess that's not what you're after.

>>> There's probably some way of faking an options object, but I just
>>> couldn't get it to fly...
>> 
>> Why fake it?  Isn't it easy to get a real one?
> 
> I couldn't find a mechanism to do so - I poked around the code and docs for
> quite some time, but nothing was immediately obvious.

You seem to have found it though.  ``docutils.core.Publisher.set_options``
returns an options object with default values.

> The docs don't seem to have much at all regarding the "API".

True.  It's on the list.  But I think most Docutils API docs will remain in
the docstrings for the time being.  The API itself is not mature enough to
fix the API in external docs yet.

It will help once PySource or equivalent is complete and part of Docutils
proper; API docs will be auto-generated from docstrings, mostly.  That is my
intended focus over the next few weeks.

>>> The Reporter stuff seemed far too hard-coded for my brain to cope
>>> with at present :)
>> 
>> Are you trying to capture the stderr output of Reporter, or the
>> <system_message> elements it produces?  Why?
> 
> I'd want to get the actual message elements, so I can display them sensibly as
> I described above.

The <system_message> elements are inserted into the document tree, adjacent
to the problems themselves where possible.  Some (those generated
post-parse) are kept until later, in ``document.messages``, and added as a
special final section, "Docutils System Messages".

Would you want these messages *not* to be in the document?  Or would a list
of references be enough?  Docutils could be made to generate hyperlinks to
all known system_messages and add them to the document.

-- 
David Goodger  <go...@us...>  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/